ICEnroll4::createPKCS10 Method

[This method is available for use in the operating systems specified in the Requirements section.]

The createPKCS10 method creates a base64-encoded PKCS #10 certificate request. This method was first defined in the ICEnroll interface.

This base64-encoded PKCS #10 certificate request (in BSTR form) can be submitted to a certification authority to request that a certificate be issued to the person or entity whose information it contains.

Syntax

C++ 
HRESULT createPKCS10(
  [in]  BSTR DNName,
  [in]  BSTR Usage,
  [in]  BSTR *pPKCS10
);

Parameters

DNName [in]

The distinguished name (DN) of the entity for which the request is being made. In this parameter, the DN name must follow the X.500 naming convention. For example "CN=User, O=Microsoft". If a two-letter prefix does not exist, an OID may be provided instead.

Usage [in]

An object identifier (OID) that describes the purpose of the certificate being generated. For example, Individual or Commercial Authenticode certificate, or Client Authentication. You can also specify multiple OIDs separated by a comma.

The OID is passed through to the PKCS #10 request. For general extensibility and ease of understanding, the control does not attempt to understand specific-purpose OIDs. Therefore if you specify a Client Authentication OID, the generated key will still be a signature key, not an exchange key.

pPKCS10 [in]

The returned base64-encoded PKCS10 certificate request.

Return Value

The return value is an HRESULT. A value of S_OK indicates success. Upon successful completion of this function, pPKCS10 will contain a base64-encoded PKCS #10 request (in BSTR form). The format is such that it can be directly posted to a Web server for processing.
VBScript 

Function createPKCS10( _
  ByVal DNName, _
  ByVal Usage _
)

Parameters

DNName [in]

The distinguished name (DN) of the entity for which the request is being made. In this parameter, the DN name must follow the X.500 naming convention. For example "CN=User, O=Microsoft". If a two-letter prefix does not exist, an OID may be provided instead.

Usage [in]

An object identifier (OID) that describes the purpose of the certificate being generated. For example, Individual or Commercial Authenticode certificate, or Client Authentication. You can also specify multiple OIDs separated by a comma.

The OID is passed through to the PKCS #10 request. For general extensibility and ease of understanding, the control does not attempt to understand specific-purpose OIDs. Therefore if you specify a Client Authentication OID, the generated key will still be a signature key, not an exchange key.

Return Value

The returned base64-encoded PKCS10 certificate request.

Remarks

By default, the Microsoft Base Cryptographic Provider is used, PROV_RSA_FULL is the provider type, a signature key is created, and a unique new key set is created.

When this method is called from script, the method displays a user interface that asks whether the user will allow creation of a certificate request.

Examples

BSTR bstrDN = NULL;
BSTR bstrReq = NULL;
BSTR bstrOID = NULL;
ICEnroll4 * pEnroll = NULL;
HRESULT hr;

// initialize COM
hr = CoInitializeEx( NULL, COINIT_APARTMENTTHREADED );
if (FAILED(hr))
{
    printf("Failed CoInitializeEx - %x\n", hr);
    goto error;
}

hr = CoCreateInstance( __uuidof(CEnroll),
                       NULL,
                       CLSCTX_INPROC_SERVER,
                       __uuidof(ICEnroll4),
                       (void **)&pEnroll);
if (FAILED(hr))
{
    printf("Failed CoCreateInstance - pEnroll [%x]\n", hr);
    goto error;
}
// generate the DN for the cert request
bstrDN = SysAllocString( TEXT("CN=Your Name")   // common name
                         TEXT(",OU=Your Unit")  // org unit
                         TEXT(",O=Your Org")    // organization
                         TEXT(",L=Your City")   // locality
                         TEXT(",S=Your State")  // state
                         TEXT(",C=Your Country") );  // country/region
if (NULL == bstrDN)
{
    printf("Memory allocation failed for bstrDN.\n");
    goto error;
}

// generate the OID, for example, "1.3.6.1.4.1.311.2.1.21".
bstrOID = SysAllocString(TEXT("<OIDHERE>"));
if (NULL == bstrOID)
{
    printf("Memory allocation failed for bstrOID.\n");
    goto error;
}

// create the PKCS10
hr = pEnroll->createPKCS10( bstrDN, bstrOID, &bstrReq );
if (FAILED(hr))
{
    printf("Failed createPKCS10 - %x\n", hr);
    goto error;
}
else
    // do something with the PKCS10 (bstrReq);

error:

//clean up resources, etc.
if ( bstrDN )
    SysFreeString( bstrDN );
if ( bstrOID )
    SysFreeString( bstrOID );
if ( bstrReq )
    SysFreeString( bstrReq );
if ( pEnroll )
    pEnroll->Release();

CoUninitialize();

Requirements

Minimum supported clientWindows XP
Minimum supported serverWindows Server 2003
HeaderXenroll.h
LibraryUuid.lib
DLLXenroll.dll
IIDIID_ICEnroll4 is defined as c1f1188a-2eb5-4a80-841b-7e729a356d90

See Also

ICEnroll4
ICEnroll3
ICEnroll2
ICEnroll
CEnroll

Send comments about this topic to Microsoft

Build date: 11/16/2009

Tags :


Community Content

Jonni Faiga
C# code example of generating a Base24 encoded PKCS10 request on Windows Vista and pre Windows Vista
The following C# code is an example of generating a Base24 encoded PKCS10 request on Windows Vista, and pre Windows Vista.
internal static string CreatePKCS10(string strDN)
{
    if (Environment.OSVersion.Version.Major >= 6)
        return CreatePKCS10_ViaCertEnroll(strDN);
    else  // XP/2003 and earlier
        return CreatePKCS10_ViaXEnroll(strDN);
}
internal static string CreatePKCS10_ViaCertEnroll(string strDN)
{
    // Create a PKCS10 request based on the "User" Template, which implies the following OIDs:
    //      Encrypting File System (1.3.6.1.4.1.311.10.3.4)   // XCN_OID_KP_EFS
    //      Secure Email (1.3.6.1.5.5.7.3.4)  // XCN_OID_PKIX_KP_EMAIL_PROTECTION
    //      Client Authentication (1.3.6.1.5.5.7.3.2) // XCN_OID_PKIX_KP_CLIENT_AUTH

    CX500DistinguishedName cX500DistinguishedName = new CX500DistinguishedName();
    cX500DistinguishedName.Encode(strDN, X500NameFlags.XCN_CERT_NAME_STR_NONE);

    CX509CertificateRequestPkcs10 request = new CX509CertificateRequestPkcs10();
    // Note: X509CertificateEnrollmentContext.ContextMachine requires Administrative access
    request.InitializeFromTemplateName(X509CertificateEnrollmentContext.ContextUser, "User");
    request.Subject = cX500DistinguishedName;

    request.Encode();
    string pkcs10request = request.get_RawData(EncodingType.XCN_CRYPT_STRING_BASE64);
    // System.Runtime.InteropServices.Marshal.ReleaseComObject not called since client application
    // (see http://blogs.msdn.com/cbrumme/archive/2003/04/16/51355.aspx)
    return pkcs10request;
}
internal static string CreatePKCS10_ViaXEnroll(string strDN)
{
    // Create a PKCS10 request for ClientAuthentication only
    string OID_CLIENT_AUTHENTICATION = "1.3.6.1.5.5.7.3.2";
    Type oEnrollType = Type.GetTypeFromProgID("CEnroll.CEnroll.1",true);
    ICEnroll oEnroll = (ICEnroll)Activator.CreateInstance(oEnrollType);
    return oEnroll.createPKCS10(strDN, OID_CLIENT_AUTHENTICATION);
}


Page view tracker