ICEnroll::PVKFileName [C++]

CEnroll.PVKFileName [Visual Basic]

The PVKFileName property is provided for exporting keys (subject to the capabilities of the cryptographic service provider).

[Visual Basic]
objEnroll.PVKFileName [ = FileName ]
[C++]
HRESULT put_PVKFileName(BSTR FileName);
HRESULT get_PVKFileName(BSTR * pFileName);

Parameters

[Visual Basic] objEnroll

Object expression that resolves to a CEnroll object.

[Visual Basic,C++] FileName

The string value assigned to the PVKFileName property. It can be any valid filename supported by your operating system.

[C++] pFileName

Pointer to retrieved property value.

Remarks

PVKFileName affects the behavior of the following methods:

• createPKCS10
• createFilePKCS10

Historically, Authenticode has exported the private key to a .pvk file on a disk and removed the keys from the registry. By default, private keys are not generated for exportation, and many cryptographic service providers do not support exporting keys. However, if the cryptographic service provider (CSP) can support exporting private keys, setting the PVKFileName property will attempt to generate the private keys as exportable. Setting the property will also write the private and public key to the file specified by the PVKFileName property. As a byproduct, the private key is removed from the CSP. The filename specified by the property can be any accessible file. By default, no .pvk file is generated and the keys are not generated as exportable.

If the .pvk file already exists, the user is notified and prompted for permission to overwrite.

The GenKeyFlags property also has a flag that controls whether the private key can be exported. Use care when utilizing the GenKeyFlags property and the PVKFileName property together. If the PVKFileName property is set first, the GenKeyFlags property is automatically set to CRYPT_EXPORTABLE. If the GenKeyFlags property is set (using the put_GenKeyFlags function) in this case without setting CRYPT_EXPORTABLE flag, then the GenKeyFlags will not be set to CRYPT_EXPORTABLE and the generated keys will not be exportable. The following example demonstrates this:

1. Call put_PVKFileName to set the filename for the file that will receive the exported keys. The GenKeyFlags property is automatically set to CRYPT_EXPORTABLE.
2. Call put_GenKeyFlags with a value not set to CRYPT_EXPORTABLE; for example, zero.
3. GenKeyFlags is no longer set to CRYPT_EXPORTABLE (the value that was automatically set in step one).

Any keys generated following the previous steps will be not exportable. Therefore, it is recommended that the user set the GenKeyFlags property before the PVKFileName property when they are used together.

Alternatively, the user could determine the current value of the CRYPT_EXPORTABLE bit in the GenKeyFlags property, and then OR this value into any changes that are made to the GenKeyFlags property to ensure that the bit is not wiped out. The user could also specifically set the CRYPT_EXPORTABLE bit when updating the GenKeyFlags property.

Example Code [C++]

BSTR     bstrPVKFile = NULL;
BSTR     bstrNewPVKFile = NULL;
HRESULT  hr;

// pEnroll is previously instantiated ICEnroll interface pointer

// get the PVKFileName
hr = pEnroll->get_PVKFileName( &bstrPVKFile );
if (FAILED( hr ))
    printf("Failed get_PVKFileName - %x\n", hr );
else
    printf( "PVKFileName: %ws\n", bstrPVKFile );
// free BSTR when done
if ( NULL != bstrPVKFile )
    SysFreeString( bstrPVKFile );

// set the PVKFileName
bstrNewPVKFile = SysAllocString(TEXT("MyKeys.pvk"));

hr = pEnroll->put_PVKFileName( bstrNewPVKFile );
if (FAILED( hr ))
    printf("Failed put_PVKFileName - %x\n", hr );
else
    printf( "PVKFileName set to %ws\n", bstrNewPVKFile );
// free BSTR when done
if ( NULL != bstrNewPVKFile )
    SysFreeString( bstrNewPVKFile ); 

Example Code [Visual Basic]

' declare Certificate Enrollment Control object
Dim objXen As Object

Dim strPVKFile As String

' instantiate the object
Set objXen = CreateObject("CEnroll.CEnroll.1")

' retrieve and display the PVKFileName
strPVKFile = objXen.PVKFileName
MsgBox strPVKFile, vbOKOnly, "PVKFileName"

' set the PVKFileName
objXen.PVKFileName = "MyFile.PVK"

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.