ICertServerPolicy::SetCertificateProperty method (certif.h)

Use the SetCertificateProperty 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.

Value Meaning
NotBefore
Date/time
The certificate is not valid before the given date.
NotAfter
Date/time
The certificate is not valid after the given date.
GeneralFlags
Set this property to 0x00000400 to prevent the request 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 Server 2003:  This field is not supported.
CrossForest
PROPTYPE_LONG
A Boolean value that specifies whether the CA should operate cross forest enrollment mode.

Windows Server 2008 and Windows Server 2003:  Cross forest enrollment is not supported. Cross forest enrollment is supported beginning with Windows Server 2008 R2.

RequesterSAMName
PROPTYPE_STRING
Tells the CA to set the requester account name ("RequesterName") and distinguished name.
RequesterUPN
PROPTYPE_STRING
Tells the CA to convert the user principal name (UPN) of the requester to the requester name ("RequesterName") and to set the requester name and the requester distinguished name.
RequesterDN
PROPTYPE_STRING
Tells the CA to convert the FQDN 1779 name of the requester to the requester name and to set the requester 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.

Value Meaning
PROPTYPE_LONG
Signed long data.
PROPTYPE_DATE
Date/time data.
PROPTYPE_BINARY
Binary data.
PROPTYPE_STRING
Unicode string data

[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 SetCertificateProperty:

  • 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 SetCertificateProperty 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

Requirement Value
Minimum supported client None supported
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header certif.h (include Certsrv.h)
Library Certidl.lib
DLL Certcli.dll

See also

ICertServerExit::GetCertificateProperty

ICertServerPolicy

ICertServerPolicy::SetContext

Name Properties