3.2.4.1.1 GetOCSPProperty (Opnum 3)
This method retrieves the value of a responder property from the Online Responder Service.
-
HRESULT GetOCSPProperty( [in, ref] const BSTR bstrEntryName, [out, ref] VARIANT* pEntryValue );
bstrEntryName: A BSTR that specifies the name of the property to retrieve. The Unicode string value SHOULD be one of the values listed in ResponderProperties or one of the following values.
-
Property name
Meaning
CAEntries
A list of strings containing the RevocationConfigurationId corresponding to each configured revocation configuration in RevocationConfigurationList.
AllEntries
A list of all the configured properties in the list ResponderProperties and all the revocation configuration properties for all revocation configurations in RevocationConfigurationList.
pEntryValue: A pointer to a VARIANT. The data returned is the value of the property referenced by bstrEntryName. See the following table for the processing rules that apply to the bstrEntryName values. Other, vendor-defined bstrEntryName values, not defined in the following table, MAY be used, as described in the processing rules that follow the table.
-
Property name
Processing rule for data returned
AuditFilter
The vt member of the VARIANT referenced by pEntryValue MUST be set to VT_I4, and the lVal member MUST be either 0 or a bitwise OR of the following values.
Flag value – Meaning
0x00000000 – Nothing is Audited.
0x00000001 – Audit start/stop of the service.
0x00000002 – Audit changes to the revocation configurations on the responder.
0x00000004 – Audit OCSP requests received by the responder.
0x00000008 – Audit changes to the security descriptor on the responder.
ArrayController
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_BSTR, and the bstrVal member SHOULD be BSTR for the Unicode string value of the Domain Name System (DNS) name of the machine designated as Array controller for the array of responder machines.
ArrayMembers
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_ARRAY | VT_BSTR, and the pArray member SHOULD reference a single dimension safearray. The number of elements of the safearray referenced by pArray SHOULD be equal to the number of machines running Online Responder Service with the same configuration information. For each machine, there SHOULD be an element in the safearray referenced by pArray containing the BSTR for Unicode string value of the FQDN of the machine.
NumOfThreads
The vt member of the VARIANT referenced by pEntryValue MUST be set to VT_I4, and the lVal member MUST be set to the maximum number of simultaneous OCSP requests [MS-OCSP] that can be served by the Online Responder Service. <5>
MaxNumOfCacheEntries
The vt member of the VARIANT referenced by pEntryValue MUST be set to VT_I4, and the lVal member MUST be the maximum number of OCSP responses that can be cached by the responder.
CAEntries
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_ARRAY | VT_BSTR, and the pArray member SHOULD reference a single dimension safearray. The number of elements of the safearray reference by pArray SHOULD be equal to the number of entries in RevocationConfigurationList. For each revocation configuration in RevocationConfigurationList, there SHOULD be an element containing the BSTR for the Unicode string value of the RevocationConfigurationId.
LogLevel
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_I4, and the lVal member SHOULD be set to the integer value that specifies the level of information to be communicated to the system (application eventlog channel) as part of operations being performed on the service.<6>
Debug
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_I4, and the lVal member SHOULD be an integer value that specifies whether tracing for errors on the responder is enabled or not.<7>
EnrollPollInterval
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_I4, and the lVal member SHOULD be set to the integer value that specifies the frequency (in number of hours) with which the responder will attempt to enroll for a signing certificate (for signing OCSP responses).<8>
RequestFlags
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_I4, and the lVal member SHOULD be either 0 or the following value.
Flag value – Meaning
0x00000001:Responder MUST reject OCSP requests that have signatures on them.
MaxIncomingMessageSize
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_I4, and the lVal member SHOULD be set to the integer value that specifies the maximum size of the OCSP request [MS-OCSP], in bytes, that is allowed to be processed on the server.
NumOfBackendConnections
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_I4, and the lVal member SHOULD be set to the integer value that specifies the maximum number of connections that can be created by the web server to the Online Responder Service. <9>
RefreshRate
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_I4, and the lVal member SHOULD be set to the integer value that specifies the frequency (in number of milliseconds) with which the web server will attempt to contact the Online Responder Service to obtain the latest revocation configuration information.
MaxAge
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_I4, and the lVal member SHOULD be set to the integer value that specifies the value for the HTTP max-age cache-control directive [RFC2616] as part of the OCSP response.
ISAPIDebug
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_I4, and the lVal member SHOULD be set to the integer value that specifies whether the tracing for errors on the web server is enabled or not.<10>
MaxNumOfRequestEntries
The vt member of the VARIANT referenced by pEntryValue SHOULD be set to VT_I4, and the lVal member SHOULD be set to the integer value that specifies the maximum number of requests that can be included in the requestList field of the OCSPRequest structure ([RFC2560] section 4.1.1).<11>
AllEntries
The vt member of the VARIANT MUST be set to VT_ARRAY | VT_VARIANT, and 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 sum of the number of entries in ResponderProperties and the number of entries in the RevocationConfigurationList. For each property in ResponderProperties, the first column of the row MUST be a VARIANT with vt member as VT_BSTR and the bstrVal member MUST be BSTR for the Unicode string value of the name of the property. The second column of the row MUST be a VARIANT with the value defined in this table, corresponding to the name of the property. For each revocation configuration in RevocationConfigurationList, the first column of the row MUST be a VARIANT with vt member as VT_BSTR and the bstrVal member MUST be BSTR for the Unicode string value of RevocationConfigurationId. The second column of the row MUST be a VARIANT with the value defined in section 3.2.4.1.3.
The following additional processing rules apply:
If the value of bstrEntryName is not the same as one of the values specified in the preceding list or of a vendor-defined property, or if the property with the same name is not yet configured on the responder, the server MUST fail. The error code SHOULD be 0x80070002.
If the value of bstrEntryName corresponds to a vendor-defined property, the server MAY return the value as a VARIANT containing data of the type integer, string, date, or binary object. Otherwise, for bstrEntryName values that do not correspond to the previous list, the server responds as if the property were not yet configured on the responder.<12>