GetCertificateExtensionFlags Method

ICertServerExit::GetCertificateExtensionFlags method

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

Syntax


HRESULT GetCertificateExtensionFlags(
  [out] LONG *pExtFlags
);

Parameters

pExtFlags [out]

A pointer to a LONG variable that will contain the extension flags.

Return value

C++

If the method succeeds, the method returns S_OK, and *pExtFlags is set to the variable that contains the flags from the extension acquired by the most recent call to ICertServerExit::GetCertificateExtension.

If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see Common HRESULT Values.

VB

The return value is the flags from the extension acquired by the most recent call to ICertServerExit::GetCertificateExtension.

Remarks

There are two kinds of flags used in extensions: policy flags and origin flags.

Flag typeExplanation
PolicyProvides information about the certificate extension. Policy flags can be set by the policy module.
OriginIndicates 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 valueExplanation
EXTENSION_CRITICAL_FLAGThis is a critical extension.
EXTENSION_DISABLE_FLAGExtension will not be used.

 

One of the following origin flags can also be returned.

Origin flag valueExplanation
EXTENSION_ORIGIN_REQUESTThe extension was extracted from an array of extensions stored in the szOID_CERT_EXTENSIONS (1.3.6.1.4.1.311.2.1.14) or szOID_RSA_certExtensions (1.2.840.113549.1.9.14) attribute of a PKCS #10 request.
EXTENSION_ORIGIN_POLICYThe policy module set the extension.
EXTENSION_ORIGIN_ADMINThe administrator set the extension. For more information, see ICertAdmin::SetCertificateExtension.
EXTENSION_ORIGIN_SERVERThe server engine set the extension.
EXTENSION_ORIGIN_RENEWALCERTThe extension was extracted from the certificate stored in the szOID_RENEWAL_CERTIFICATE (1.3.6.1.4.1.311.13.1) attribute of a PKCS #10 renewal request.
EXTENSION_ORIGIN_IMPORTEDCERTThe extension was extracted from an imported certificate (the certificate was passed to ICertAdmin::ImportCertificate).
EXTENSION_ORIGIN_PKCS7The extension was extracted from an array of extensions stored in the szOID_CERT_EXTENSIONS (1.3.6.1.4.1.311.2.1.14) or szOID_RSA_certExtensions (1.2.840.113549.1.9.14) attribute of a PKCS #7 request.

 

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

Mask valueExplanation
EXTENSION_POLICY_MASKThis value (0x0000FFFF) is used to examine policy flags.
EXTENSION_ORIGIN_MASKThis value (0x000F0000) is used to examine origin flags.

 

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.

You must call ICertServerExit::SetContext prior to using this method.

Examples


HRESULT  hr;
LONG     ExtFlags;

// pCertServerExit has been used to call SetContext previously.
hr = pCertServerExit->GetCertificateExtensionFlags(&ExtFlags);

// More than one policy flag may be set.
LONG ExtPolicyFlags = ExtFlags & EXTENSION_POLICY_MASK;

if (ExtPolicyFlags & EXTENSION_CRITICAL_FLAG)
{
    // Perform the desired operation.
}

if (ExtPolicyFlags & EXTENSION_DISABLE_FLAG)
{
    // Perform the desired operation.
}

// 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 administrator.
        break;
    case EXTENSION_ORIGIN_SERVER:
        // Extension was set by server engine.
        break;
    case EXTENSION_ORIGIN_RENEWALCERT:
        // Extension was set by renewal certificate.
        break;
    case EXTENSION_ORIGIN_IMPORTEDCERT:
        // Extension was set by imported certificate.
        break;
    case EXTENSION_ORIGIN_PKCS7:
        // Extension was set by PKCS #7.
        break;
    default:
        break;
}

Requirements

Minimum supported client

None supported

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Certif.h (include Certsrv.h)

Library

Certidl.lib

DLL

Certcli.dll

IID

IID_ICertServerExit is defined as 4BA9EB90-732C-11D0-8816-00A0C903B83C

See also

ICertServerExit
CCertServerExit
ICertServerExit::GetCertificateExtension
IEnumCERTVIEWEXTENSION::GetFlags
ICertAdmin::SetCertificateExtension

 

 

Show:
© 2016 Microsoft