3.2.4.1.3 GetCAConfigInformation (Opnum 5)

  • Article

The GetCAConfigInformation method retrieves all the properties associated with a particular revocation configuration.

 HRESULT GetCAConfigInformation(
   [in, ref] const BSTR bstrCAId,
   [out, ref] VARIANT* pEntryValue
 );

bstrCAId: A BSTR that specifies the RevocationConfigurationId for the revocation configuration whose properties are to be retrieved.

pEntryValue: A pointer to a VARIANT data type that contains the names and values of all configured revocation configuration properties.

The following processing rules apply:

  1. The server MUST look in the RevocationConfigurationList for the revocation configuration whose RevocationConfigurationId value is the same as the bstrCAId value. This is a case-insensitive lookup. If the revocation configuration is not found, then the responder MUST fail the request. The error code SHOULD be 0x800710d8.

  2. Otherwise, for the revocation configuration identified by bstrCAId, the server MUST return the properties associated with it as the value of pEntryValue. The server MUST set the vt member of the VARIANT referenced by pEntryValue to VT_ARRAY | VT_VARIANT. The pArray member of the VARIANT referenced by pEntryValue MUST reference a two-dimensional safearray. The number of elements in the second dimension (signifying the number of columns) of the safearray referenced by pArray MUST be 2. The number of elements in the first dimension (signifying the number of rows) of the safearray referenced by pArray MUST be set to the number of properties for the revocation configuration. For each revocation configuration property, the first column of the row MUST be a VARIANT with vt member set to VT_BSTR, and the bstrVal member set to the BSTR for the Unicode string value of the name of the property. The second column of the row MUST be a VARIANT with value defined in the following table, in the row corresponding to the name of the property.

     Property name

     Processing rule

    CACertificate

    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 MUST be equal to the length in bytes of the ASN.1 DER encoding of the CA certificate for which this revocation configuration is configured.

    HashAlgorithmId

    The vt member of the VARIANT MUST be set to VT_BSTR, and the bstrVal member MUST be the BSTR for the Unicode string value of the hash algorithm used by the responder to sign OCSP responses for this revocation configuration.<14>

    SigningFlags

    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.

    0x00000002 - The server is configured to use the CA certificate for this revocation configuration to sign the OCSP responses.

    0x00000010 - The revocation configuration is configured to look for an OCSP certificate that has the designated OCSP signing certificate enhanced key usage in its extension (see OCSP [RFC2560]).

    0x00000020 - The revocation configuration is configured to require that an OCSP signing certificate be designated manually by setting the "SigningCertificate" property.

    0x00000004 - When a delegated signing certificate (as defined in [RFC2560]) is used for generating responses, the revocation configuration is configured to use the renewed signing certificate automatically, whenever such a certificate becomes available at the responder machine. Renewal is described in [MS-WCCE].

    0x00000040 - The responder is configured to include the signing public key hash in responses for this revocation configuration. (See [RFC2560] for OCSP server identifier details.)

    0x00000080 - The responder is configured to include the signing certificate subject in responses for this revocation configuration. (See [RFC2560] for OCSP server identifier details.)

    0x00000100 - The responder is configured to accept a nonce in the request. (See [RFC2560] nonce extensions in the OCSP request.)

    0x00000001 – For this revocation configuration, the responder is configured to silently acquire the private key associated with the signing certificate identified by the "SigningCertificate" property.

    0x00000008 - If this value is set, the responder is configured only to use signing certificates issued by the same cryptographic key as the CA for which this revocation configuration is configured.

    0x00000200 – For this revocation configuration, the responder is configured to enroll for a signing certificate from the CA defined by the property "CAConfig" using the certificate template defined by the property "SigningCertificateTemplate".

    ReminderDuration

    The vt member of the VARIANT MUST be set to VT_I4, and the lVal member MUST be a DWORD value denoting the percentage of the signing certificate’s lifetime, after which, if the signing certificate is not renewed, a warning event will be logged.

    SigningCertificate

    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 referenced by pArray MUST be equal to the length in bytes of the ASN.1 DER encoding of the signing certificate used by the responder to sign OCSP responses for this revocation configuration.

    ErrorCode

    The vt member of the VARIANT MUST be set to VT_I4, and the lVal member MUST be the HRESULT DWORD value denoting the status of this revocation configuration. A value of 0 implies that this revocation configuration is properly configured with an OCSP signing certificate and that the cryptographic key pair associated with the signing certificate is accessible and ready to use for signing OCSP responses. See [MS-ERREF] for a list of the possible error codes.

    CAConfig

    The vt member of the VARIANT MUST be set to VT_BSTR, and the bstrVal member MUST be the BSTR for the Unicode string for the CA configuration string [MS-WCCE] to which the responder submits the certificate request for the signing certificate.

    SigningCertificateTemplate

    The vt member of the VARIANT MUST be set to VT_BSTR, and the bstrVal member MUST be the BSTR for the Unicode string for the common name of the certificate template [MS-CRTD] to be used by the responder to create a certificate request for signing certificate.

    LocalRevocationInformation

    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 MUST be equal to the length in bytes of the ASN.1 encoded CRL to be used for local revocation checking at the responder for a particular revocation configuration.

    CSPName

    The vt member of the VARIANT MUST be set to VT_BSTR, and the bstrVal member MUST be the BSTR for the Unicode string value of the cryptographic service provider (CSP) used by the responder to sign OCSP responses for this revocation configuration.

    KeySpec

    The vt member of the VARIANT MUST be set to VT_I4, and the lVal member MUST be the key Specification. The possible values are based on the SigningCertificate and the following rules:

    Flag value – Meaning

    0x00000000 - The asymmetric key-pair associated with the SigningCertificate and used for signing could be either an encryption key or a signing key type.

    0x00000001 - The asymmetric key-pair associated with the SigningCertificate and used for signing is an encryption key type.

    0x00000002 - The asymmetric key-pair associated with the SigningCertificate and used for signing is a signing key type.

    ProviderCLSID

    The vt member of the VARIANT MUST be set to VT_BSTR, and the bstrVal member must be the BSTR for the Unicode string representation of CLSID for the revocation provider COM server that is used by this revocation configuration to check the status of a certificate.<15>

    Provider

    This is a VARIANT data type that contains the value of the properties of the revocation provider.

    The vt member of the VARIANT MUST be set either to VT_EMPTY or VT_ARRAY | VT_VARIANT.

    If the vt member is set to VT_ARRAY | VT_VARIANT, then the pArray member MUST reference a two-dimensional safearray. The number of elements in the second dimension (signifying the number of columns) of the safearray referenced by pArray MUST be 2. The number of elements in the first dimension (signifying the number of rows) of the safearray referenced by pArray MUST be set to the number of properties for the revocation provider. For each revocation provider property, the first column of the row MUST be a VARIANT with vt member set to VT_BSTR, and the bstrVal member set to the BSTR for the Unicode string value of the revocation provider property name. The second column of the row MUST be a VARIANT with the value defined in the following table (corresponding to the name of the revocation provider property).

    The following table gives the processing rules for the revocation provider.

     Property name

     Processing rules

    CrlUrlTimeOut

    The vt member of the VARIANT MUST be set to VT_I4, and the lVal member MUST be the time-out in milliseconds that the revocation provider must wait before it times out while trying to retrieve the CRL for which it is configured.

    BaseCrlUrls

    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 URIs from where a base CRL [RFC3280] can be retrieved. For each URI, there MUST be an element in safearray referenced by pArray containing the BSTR for the Unicode string value of the URI.

    DeltaCrlUrls

    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 URIs from where a delta CRL [RFC3280] can be retrieved. For each URI, there MUST be an element in safearray referenced by pArray containing the BSTR for the Unicode string value of the URI.

    BaseCrl

    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 referenced by pArray MUST be equal to the length in bytes of the ASN.1 encoded binary representation of the Base CRL loaded by the revocation provider.

    DeltaCrl

    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 referenced by pArray MUST be equal to the length in bytes of the ASN.1 encoded binary representation of the Delta CRL loaded by the revocation provider.

    RefreshTimeout

    The vt member of the VARIANT MUST be set to VT_I4, and the lVal member MUST be the time-out value in milliseconds associated with refreshing the CRL information.

    RevocationErrorCode

    The vt member of the VARIANT MUST be set to VT_I4, and the lVal member MUST be the HRESULT DWORD value denoting the status of this revocation provider. A value of 0 means that the revocation provider can provide certificate revocation status for certificates issued by the certificate authority configured for the revocation configuration. See [MS-ERREF] for a list of the possible error codes.

    IssuedSerialNumbersDirectories

    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 UNC or local file paths that are being used by the CA to store the serial numbers of certificates.<16>