ICertServerPolicy::SetCertificateProperty

The SetCertificateProperty method causes the Server Engine to add a named property to a certificate.

[VB] void SetCertificateProperty(
  BSTR strPropertyName,        
  long PropertyType,           
  VARIANT * pvarPropertyValue  
);
 
[JAVA] void SetCertificateProperty(
  java.lang.String strPropertyName,  
  int PropertyType,                  
  com.ms.Variant * pvarPropertyValue  
);
 
[C++] HRESULT SetCertificateProperty(
  BSTR const strPropertyName,  // in
  LONG PropertyType,           // in
  VARIANT *pvarPropertyValue   // in
);
 

Parameters

[VB][JAVA][C++] strPropertyName

Specifies the named property to set. There are a stock set of certificate properties that are always valid, referred to as the Name Properties. Other properties valid for certificates that may be set by SetCertificateProperty include the Certifcate Properties listed below.

Name Properties

These properties can refer to the subject name or the issuer name by prepending Subject or Issuer to the property. For example, Subject.OrgUnit would refer to the subject's organizational unit. Name properties must in general be 49 or less non-null characters in length except where noted.

Note  Only Subject name properties are supported in this release (do not prepend Issuer to a property name.)

Property Name	Data Type	Description
DistinguishedName	String	Full X.400 DN Name (must be 254 non-null characters or less)
Country	String	X.500 2-character country code (for example US for United States or CA for Canada)
Organization	String	Legal name of organization
OrgUnit	String	Name of sub-organization or department
CommonName	String	Fully qualified hostname/path used in DNS (Domain Name System) lookups (for example, host.company.com)
StreetAddress	String	Street address or PO Box
Locality	String	Name of city
State	String	Full name of state or province (for example, California)
Title	String	Title of individual who requested the certificate (optional)
GivenName	String	First name of individual
Initials	String	Initials of individual (optional)
Surname	String	Last name of individual
DomainComponent	String	Component of a DNS (Domain Name System) name
E-Mail	String	E-mail address

All of the above properties except DistinguishedName and Country support multi-valued syntax using an ANSI punctuation character as the separator, which by default must be a comma. The separator character is specified by the HKEY_LOCAL_MACHINE\SYSTEM\\CurrentControlSet\Services\CertSVC\Configuration\<CA Name>\SubjectNameSeparator (REG_SZ) entry in the system registry. This entry is set to a single character string containing a comma, by default. The first character of this string must be an ANSI punctation character to enable the multi-valued syntax. If some other character appears first, or if the registry entry is empty or missing, then multi-valued syntax is disabled.

Certificate Properties

The following properties are unique to certificates and can be set by ICertServerPolicy::SetCertificateProperty.

Property Name	Data Type	Description
NotBefore	Date / Time	Certificate start validity date
NotAfter	Date / Time	Certificate expiration date

Note  ICertServerPolicy::SetCertificateProperty can set only the NotBefore and NotAfter certificate properties. See ICertServerExit::GetCertificateProperty for a complete list of all the properties in an issued certificate.

[VB][JAVA][C++] 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. See Data Types. The Type parameter can be set to one of the following types.

Type Specifier	Data Type
PROPTYPE_LONG	Signed long data
PROPTYPE_DATE	Date / Time
PROPTYPE_BINARY	Binary data
PROPTYPE_STRING	String data

[C++] pvarPropertyValue

Specifies the value to set the property to.

Return Values

This method does not return a value.

Remarks

The NotBefore and NotAfter certificate properties constrain the lifetime during which a certificate is valid. The data type for these properties is a VARIANT date (floating point) derived from COleDateTime in OLE 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 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 prior to the CA certificate's NotAfter date.

The following C++ code sets the begin and expiration properties in the certificate:

hr = pICertServerPolicy->SetCertificateProperty("NotBefore",
    PROPTYPE_DATE, 
    BeginDate);
hr = pICertServerPolicy->SetCertificateProperty("NotAfter",
    PROPTYPE_DATE, 
    ExpireDate);
 

QuickInfo

  Windows NT: Requires version 5.0 or later (or version 4.0 with the Windows NT 4.0 Option Pack).
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in certif.h.
  Import Library: Use certidl.lib.