ICEnroll::createFilePKCS10 [C++]

CEnroll.createFilePKCS10 [Visual Basic]

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

This method differs from createPKCS10 only in saving the base64-encoded PKCS #10 (in BSTR form) to the file specified by wszPKCS10FileName.

[Visual Basic]
objEnroll.createFilePKCS10( _
            DNName As String , _
            Usage As String , _
            wszPKCS10FileName As String )
[C++]
HRESULT createFilePKCS10(
  BSTR DNName,            // in
  BSTR Usage,             // in
  BSTR wszPKCS10FileName  // in
);

Parameters

[Visual Basic] objEnroll

Object expression that resolves to a CEnroll object.

[Visual Basic,C++] DNName

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

[Visual Basic,C++] Usage

An 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.

This purpose OID is merely 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 keys will still be signature keys, not exchange keys.

[Visual Basic,C++] wszPKCS10FileName

Designates a file in which the base64-encoded PKCS #10 (in BSTR form) is saved.

Return Values

[Visual Basic] None.

[C++] The return value is an HRESULT. A value of S_OK indicates success. Upon successful completion of this function, the file specified in wszPKCS10FileName 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.

Remarks

By default, the Microsoft Base Cryptographic Provider is used, and a unique signature key is created.

Example Code [C++]

BSTR       bstrDN = NULL;
BSTR       bstrOID = NULL;
BSTR       bstrFileName = NULL;
ICEnroll * pEnroll = NULL;
HRESULT    hr;

// Initialize COM.
hr = CoInitializeEx( NULL, COINIT_APARTMENTTHREADED );

if (FAILED(hr))
{
    printf("Failed CoInitializeEx - %x\n", hr);
    goto error;
}

hr = CoCreateInstance( CLSID_CEnroll,
                       NULL,
                       CLSCTX_INPROC_SERVER,
                       IID_ICEnroll,
                       (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=Redmond")     // locality
                         TEXT(",S=Washington")  // state
                         TEXT(",C=US") );       // country/region

// Generate the OID.
bstrOID = SysAllocString(TEXT("1.3.6.1.4.1.311.2.1.21"));

// Specify the file name.
bstrFileName = SysAllocString(TEXT("myPKCS10.req"));

// Create the PKCS10 (stored in a file).
hr = pEnroll->createFilePKCS10( bstrDN, bstrOID, bstrFileName );

if (FAILED(hr))
{
        printf("Failed createFilePKCS10 - %x\n", hr);
        goto error;
}
else
    // Success.
    printf("Successfully created file containing PKCS10\n");

error:
// Clean up resources etc.

if ( NULL != bstrFileName )
    SysFreeString( bstrFileName );

if ( NULL != bstrDN )
    SysFreeString( bstrDN );

if ( NULL != bstrOID )
    SysFreeString( bstrOID );

if ( NULL != pEnroll )
       pEnroll->Release();

CoUninitialize();

Example Code [Visual Basic]

' Generate the distinguished name string.
Dim strDN As String
strDN = "CN=Your Name"           ' common name
strDN = strDN & ",OU=Your Unit"  ' org unit
strDN = strDN & ",O=Your Org"    ' organization
strDN = strDN & ",L=Redmond"     ' locality
strDN = strDN & ",S=Washington"  ' state
strDN = strDN & ",C=US"          ' country/region

' The following variable is the file used to store the PKCS10.
Dim strFileName As String
strFileName = "myPKCS10.req"

' objEnroll is previously created CEnroll object.
' Generate the PKCS10 string, saved to file.
Dim strPKCS10 As String
strPKCS10 = objEnroll.createFilePKCS10(strDN, _
                                       "1.3.6.1.4.1.311.2.1.21", _
                                        strFileName)

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
  Header: Declared in Xenroll.h.
  Library: Use Uuid.lib.