3.1.4.2.3 ICertAdminD2::SetCAProperty (Opnum 33)

Article
10/01/2020

The SetCAProperty method is used to set CA properties.

 HRESULT SetCAProperty(
   [in, string, unique] wchar_t const* pwszAuthority,
   [in] LONG PropId,
   [in] LONG PropIndex,
   [in] LONG PropType,
   [in] CERTTRANSBLOB* pctbPropertyValue
 );

pwszAuthority: See pwszAuthority definition in section 3.1.4.1.1.

PropId: A LONG value that specifies one and exactly one of the following property identifiers. The use of PropIds, is as specified in [MS-WCCE] section 3.2.1.4.3.2. If a value other than one of the listed values is used, the error E_INVALIDARG is returned.

Value	Meaning
0x0000001a	A binary object that contains the CA's key recovery agent (KRA) certificate to be added at the index specified by PropIndex parameter.
0x00000019	The maximum number of KRA certificates available on the CA.
0x00000018	The minimum number of KRAs to use when archiving a private key. For more information on KRA usage, see [MSFT-ARCHIVE].
0x0000001d	A collection of name and OID (1) pairs that identify the templates supported by a CA.

PropIndex: A LONG value for the index of the KRA certificate to set when the provided PropId is 0x1a. For other PropId values, it MUST be 0.

PropType: A LONG value that specifies the type of the property. This parameter MUST be one of the following values.

Value	Meaning
PROPTYPE_LONG 0x00000001	Signed LONG data
PROPTYPE_BINARY 0x00000003	Binary data
PROPTYPE_STRING 0x00000004	Unicode String data

Value

Meaning

PROPTYPE_LONG

0x00000001

Signed LONG data

PROPTYPE_BINARY

0x00000003

Binary data

PROPTYPE_STRING

0x00000004

Unicode String data

pctbPropertyValue: A pointer to CERTTRANSBLOB that specifies the new property value. The format for the value contained in CERTTRANSBLOB is specific to the PropId defined as follows.

Value of PropID	Format for values in CERTTRANSBLOB
CR_PROP_KRACERTUSEDCOUNT 0x00000018	The pb member of CERTTRANSBLOB MUST point to an unsigned integer value (little-endian format) and the cb member of CERTTRANSBLOB MUST contain the length of the bytes containing the value.
CR_PROP_KRACERTCOUNT 0x00000019	The pb member of CERTTRANSBLOB MUST point to an unsigned integer value (little-endian format) and the cb member of CERTTRANSBLOB MUST contain the length of the bytes containing the value.
CR_PROP_KRACERT 0x0000001a	The pb member of CERTTRANSBLOB MUST point to an ASN.1 DER (as specified in [ITUX690]) encoded byte array of Certificate. The cb member of CERTTRANSBLOB MUST contain the length of the array.
CR_PROP_TEMPLATES 0x0000001d	As specified in [MS-WCCE] section 3.2.1.4.3.2.29.

The following table defines the values that MUST be set for PropIndex and PropType for each one of the property values passed via PropID.

PropID value	PropIndex MUST be	PropType MUST be
0x0000001a	The minimum index is 0.	0x00000003
0x00000019	0x00000000	0x00000001
0x00000018	0x00000000	0x00000001
0x0000001d	0x00000000	0x00000004

When processing the SetCAProperty method, the server determines its behavior based on the requested property ID (PropID parameter). All valid property IDs are listed in the preceding table. The CA MUST return the error value ERROR_INVALID_PARAMETER if any of the following conditions are met:

The value of PropID is not listed in the preceding table, or
For a given PropID value the PropIndex value does not match the required values defined in the preceding table, or
For a given PropID value the PropType value does not match the required values defined in the preceding table.

The CA server MUST use the property values to modify the data (as specified in Abstract Data Model in [MS-WCCE] section 3.2.1.1) maintained by CA as part of the configuration.

The CA server MUST apply the following processing rules:

The value of CR_PROP_KRACERTUSEDCOUNT MUST be between 1 and the current configured value of CR_PROP_KRACERTCOUNT property. The initial value for CR_PROP_KRACERTCOUNT property MUST be 0.
The value to which the CR_PROP_KRACERTCOUNT property is being set MUST be less than the currently configured value of CR_PROP_KRACERTCOUNT.
If the PropIndex is greater than or equal to the property CR_PROP_KRACERTCOUNT, then the CA must increase the value of CR_PROP_KRACERTCOUNT to the value of PropIndex plus 1 each time SetCAProperty (CR_PROP_KRACERT) is called. Else, if the PropIndex is less than CR_PROP_KRACERTCOUNT, then the value of CR_PROP_KRACERTCOUNT is not changed.
When SetCAProperty(CR_PROP_TEMPLATES) is called, the CA MUST apply the following processing rules:
1. If the pctbPropertyValue, pb member doesn't have at least two separators identified by '\n', the CA MUST fail the request. The error code SHOULD be E_INVALIDARG (0x80070057), as specified in [MS-ERREF] section 2.1. Otherwise, the CA MUST continue with the following processing rules.
2. The pctbPropertyValue, pb member contains the following string:"TemplateName1\nTemplateOID1\nTemplateName2\nTemplateOID2\... ", where
  - TemplateName1 is one of the values of the cn attribute of the certificate template object that is stored in the Certificate_Template column.
  - TemplateOID1 is the value of the msPKI-Template-Cert-Template-OID attribute of the certificate template stored in the Certificate_Template column.
  Note The CA MUST ignore the TemplateOID values specified above.
3. The enrollment services container identified in [MS-WCCE] section 2.2.2.11.2 is modified with the following attribute:
  - certificateTemplates attribute: The CA MUST set this attribute with the list of template names specified in step 4.2 above.

Partager via

3.1.4.2.3 ICertAdminD2::SetCAProperty (Opnum 33)

Ressources supplémentaires