ICEnroll::createPKCS10 [C++]

CEnroll.createPKCS10 [Visual Basic]

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

[Visual Basic]
objEnroll.createPKCS10( _
            DNName As  String, _
            Usage As String ) As String
[C++]
HRESULT createPKCS10(
  BSTR DNName,    // in
  BSTR Usage,     // in
  BSTR *pPKCS10   // out
);

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 name must follow the X500 naming convention. For example "CN=User, O=Microsoft". If a two-letter prefix does not exist, an 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.

The purpose OID is just 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.

[C++] pPKCS10

The returned Base64-encoded PKCS10 certificate request.

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

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.

Example Code [C++]

BSTR       bstrDN = NULL;
BSTR       bstrReq = NULL;
BSTR       bstrOID = 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"));

// 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 ( NULL != bstrDN )
    SysFreeString( bstrDN );
if ( NULL != bstrOID )
    SysFreeString( bstrOID );
if ( NULL != bstrReq )
    SysFreeString( bstrReq );
if ( NULL != pEnroll )
       pEnroll->Release();

CoUninitialize();

Example Code [Visual Basic]

' generate the distinguished name string
Dim strDN As String, strPKCS10 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

' objEnroll is previously created CEnroll object
' generate the PKCS10 string
strPKCS10 = objEnroll.createPKCS10(strDN, "1.3.6.1.4.1.311.2.1.21")

' do something with the PKCS10 string...
MsgBox (strPKCS10)

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.