GetCertificateExtensionFlags

Historical Content Alert

This is a historical content for Windows NT 4.0 product and is presented for informative purposes only. All content in this directory is copyrighted and owned by Microsoft.

GetCertificateExtensionFlags

The GetCertificateExtensionFlags method gets the flags from the extension acquired by the most recent call to GetCertificateExtension.

[VB] long GetCertificateExtensionFlags(void);

[JAVA] int GetCertificateExtensionFlags(void);

[C++] HRESULT GetCertificateExtensionFlags(
  LONG * pExtFlags  // out, return value
);

Parameters

[C++] pExtFlags: See Return Values.

Return Values

Returns a value containing the flags from the extension acquired by the most recent call to GetCertificateExtension. There are two kinds of flags used in extensions; policy flags and origin flags.

Flag Type	Explanation
Policy	Provides information about the certificate extension. Policy flags can be set by the policy module.
Origin	Indicates the module that set the certificate extension. Origin flags are only set by the Server Engine.

One or more policy flags can be returned from an extension. The following are predefined policy flags.

Policy Flag Value	Explanation
EXTENSION_CRITICAL_FLAG	This is a critical extension.
EXTENSION_DISABLE_FLAG	Extension will not be used.

One of the following origin flags can also be returned.

Origin Flag Value	Explanation
EXTENSION_ORIGIN_REQUEST	A request set the extension.
EXTENSION_ORIGIN_POLICY	Policy module set the extension.
EXTENSION_ORIGIN_ADMIN	Admin set the extension.
EXTENSION_ORIGIN_SERVER	Server Engine set the extension.

Pre-defined masks are provided for ease of use in determining which flags are set in the return value. The following masks are provided.

Mask Value	Explanation
EXTENSION_POLICY_MASK	This value (0x0000FFFF) is used to examine policy flags.
EXTENSION_ORIGIN_MASK	This value (0x000F0000) is used to examine origin flags.

Comments

The following C++ code demonstrates use of the pre-defined mask to examine policy flags:

HRESULT hr;
LONG ExtFlags
hr = pICertServerExit->GetCertificateExtensionFlags(
    &ExtFlags);

// more than one policy flag might be set
LONG ExtPolicyFlags = ExtFlags & EXTENSION_POLICY_MASK;

if (ExtPolicyFlags & EXTENSION_CRITICAL_FLAG)
{
    // do something
}

if (ExtPolicyFlags & EXTENSION_DISABLE_FLAG)
{
    // do something
}

Note It is safe to use the high 8 bits of EXTENSION_POLICY_MASK for custom data. These bits will be saved persistently in the database, but will not be written to the certificate extensions.

The following C++ code demonstrates use of the pre-defined masks to examine origin flags:

HRESULT hr;
LONG ExtFlags
hr = pICertServerExit->GetCertificateExtensionFlags(
    &ExtFlags);

// only one origin flag can be set
switch (ExtFlags & EXTENSION_ORIGIN_MASK)
{
    case EXTENSION_ORIGIN_REQUEST:
        // extension was set in certificate request
        break;
    case EXTENSION_ORIGIN_POLICY:
        // extension was set by policy module
        break;
    case EXTENSION_ORIGIN_ADMIN:
        // extension was set by admin
        break;
    case EXTENSION_ORIGIN_SERVER:
        // extension was set by server engine
        break;
    default:
        break;
}