ICEnroll4::PVKFileName property

[This property is no longer available for use as of Windows Server 2008 and Windows Vista.]

The PVKFileName property sets or retrieves the name of the file that will contain exported keys.

This property was first defined in the ICEnroll interface.

This property is read/write.

Syntax


HRESULT put_PVKFileName(
  [in]  BSTR FileName
);

HRESULT get_PVKFileName(
  [out] BSTR *pFileName
);

Property value

A string that contains the name of the file that will contain exported keys. The string can be any valid file name supported by the operating system.

Error codes

If the property access methods put_PVKFileName and get_PVKFileName succeed, they return S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

The PVKFileName property affects the behavior of the following methods:

Exporting functionality may not be supported by the cryptographic service provider (CSP). 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 CSP supports exporting private keys, specifying a non-NULL value for the PVKFileName property causes the private keys to be generated as exportable and the private and public keys to be written to the file specified by the PVKFileName property. The private key is removed from the CSP. The file name 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 it.

The GenKeyFlags property also has a flag that controls whether the private key can be exported. Use care when using 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 (by using the put_GenKeyFlags function) without including the CRYPT_EXPORTABLE flag, then the GenKeyFlags will not be set to CRYPT_EXPORTABLE, and the generated keys will not be exportable. The following procedure demonstrates this:

  1. Call put_PVKFileName to set the file name 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 by 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 perform a bitwise-OR operation between this value and 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.

Examples


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, for example, "MyKeys.pvk"
bstrNewPVKFile = SysAllocString(TEXT("FILENAMEHERE"));

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 );

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

End of client support

Windows XP

End of server support

Windows Server 2003

Header

Xenroll.h

Library

Uuid.lib

DLL

Xenroll.dll

IID

IID_ICEnroll4 is defined as c1f1188a-2eb5-4a80-841b-7e729a356d90

 

 

Show: