The Encryption API Reference

The encryption plug-in is designed using the Component Object Model (COM) principles. A plug-in is a component (class) identified by class ID, which is a globally unique identifier (GUID). The component exposes its functionality through interfaces. Each interface provided by the component is also identified by a GUID. The access to the component is done through methods of the interfaces. The encryption plug-in interfaces are defined in the PrlPluginClasses.h header file, which is included in the Parallels Virtualization SDK. Developing a plug-in involves implementing the component, the interfaces, and a number of functions (some optional, some mandatory) that have to be exported from the dynamic library. This section provides a reference information. For a sample plug-in implementation please refer to the Implementing a Plug-in section.

Constants

PRL_CLS_NULL is a constant that defines the NULL GUID used as a terminator in the interfaces array (the array is used to hold the list of the interfaces supported by the component and is declared and populated in the plug-in implementation).

static const PRL_GUID PRL_CLS_NULL = { 0, 0, 0, { 0, 0, 0, 0, 0, 0, 0, 0 } };

PRL_CLS_BASE is a constant that defines the GUID of the base interface. The base interface provides access to the base plug-in functionality, such as creating objects, getting the plug-in info, and memory management. The base interface name is PrlPlugin and it's described later in this section.

static const PRL_GUID PRL_CLS_BASE = { 0x823067ea, 0x8e15, 0x474f,

{ 0xa3, 0xae, 0xc6, 0xa0, 0x68, 0x46, 0x12, 0x56 } };

#define GUID_CLS_BASE_STR "{823067ea-8e15-474f-a3ae-c6a068461256}"

PRL_CLS_ENCRYPTION is a constant that defines the encryption interface GUID. The encryption interface provides access to the data encryption functionality. The encryption component name is PrlCrypt and it's described later in this section.

static const PRL_GUID PRL_CLS_ENCRYPTION = { 0x564820fc, 0xe265, 0x4d69,

{ 0x9f, 0xb0, 0x3d, 0x18, 0x39, 0x6f, 0x1f, 0x8d } };

#define GUID_CLS_ENCRYPTION_STR "{564820fc-e265-4d69-9fb0-3d18396f1f8d}"

Structures

IPluginInfo is a structure that's used to hold general plug-in information.

typedef struct _IPluginInfo

{

    PRL_STR Vendor;    // Vendor info.

    PRL_STR Copyright; // Copyright info.

    PRL_STR DescShort; // Short description.

    PRL_STR DescLong;  // Long description.

    PRL_UINT32 Major;  // Major version number.

    PRL_UINT32 Minor;  // Minor version number.

    PRL_UINT32 Build;  // Build number.

    PRL_GUID Type;     // Plug-in GUID.

} PRL_STRUCT(IPluginInfo);

typedef IPluginInfo* IPluginInfoPtr;

ICryptInfo is a structure that's used to hold the plug-in info (PluginInfo) together with the key and block size values used for data encryption.

typedef struct _ICryptInfo

{

    IPluginInfo PluginInfo;

    PRL_UINT32 KeySize;

    PRL_UINT32 BlockSize;

} PRL_STRUCT(ICryptInfo);

typedef ICryptInfo* ICryptInfoPtr;

Interfaces

PrlPlugin is an interface that provides access to the base plug-in functionality, such as creating objects, getting the plug-in info, and memory management.

typedef struct _PrlPlugin

{

    // Releases the memory occupied by the structure.

    void (PRL_CALL *Release)(struct _PrlPlugin* _self);

    // Creates a specified interface.

    // This method is called by Parallels Service to create

    // the base and encryption interfaces.

    // The Class parameter specifies the GUID of

    // the interface to create: PRL_CLS_BASE or PRL_CLS_ENCRYPTION.

    // The _obj parameter receives a reference to the created interface.

    PRL_RESULT (PRL_CALL *QueryInterface)(struct _PrlPlugin* _self,

                              PRL_GUID* Class, PRL_VOID_PTR_PTR _obj);

    // Obtains a reference to the IPluginInfo structure containing the

    // plug-in info.

    PRL_RESULT (PRL_CALL *GetInfo)(struct _PrlPlugin* _self, IPluginInfoPtr Info);

} PRL_STRUCT( PrlPlugin )

PrlCrypt is an interface that provides access to the data encryption functionality.

typedef struct _PrlCrypt

{

    // Inheritance from PrlPlugin.

    struct _PrlPlugin Plugin;

    // Initializes the encryption engine.

    PRL_RESULT (PRL_CALL *Init)(struct _PrlCrypt* _self);

    // Encrypts the supplied data block.

    PRL_RESULT (PRL_CALL *Encrypt)(struct _PrlCrypt* _self, PRL_VOID_PTR Data,

                                   const PRL_UINT32 Size, const PRL_UINT8_PTR v);

    // Decrypts the supplied data block.

    PRL_RESULT (PRL_CALL *Decrypt)(struct _PrlCrypt* _self, PRL_VOID_PTR Data,

                                   const PRL_UINT32 Size, const PRL_UINT8_PTR v);

    // Sets the encryption key. The key size must be equal to or

    // larger than the one specified in the ICryptInfo structure.

    PRL_RESULT (PRL_CALL *SetKey)(struct _PrlCrypt* _self, const PRL_UINT8_PTR Key);

    // Sets the initial initialization vector. The vector size must be

    // equal to or larger than the one specified in the ICryptInfo structure as the block size.

    PRL_RESULT (PRL_CALL *SetInitIV)(struct _PrlCrypt* _self, const PRL_UINT8_PTR v);

    // Obtains a reference to the ICryptInfo structure containing the plug-in information.

    PRL_RESULT (PRL_CALL *GetInfo)(struct _PrlCrypt* _self, ICryptInfoPtr Info);

} PRL_STRUCT( PrlCrypt );

Exported functions

PrlInitPlugin is a function that is called on plug-in loading and should contain the code to do some global plug-in initialization. This function is optional.

PRL_RESULT PRL_CALL PrlInitPlugin()

PrlFiniPlugin is a function that is called on plug-in unloading and should contain the clean-up code. This function is optional.

PRL_RESULT PRL_CALL PrlFiniPlugin()

PrlGetObjectInfo is a function that is called after plug-in initialization in order to enumerate the plug-in interfaces. The InterfacesList parameter is used as output and should contain the list of GUIDs of public interfaces provided by the plug-in.

PRL_RESULT PRL_CALL PrlGetObjectInfo(PRL_UINT32 Number, PRL_GUID* Uid, PRL_GUID** InterfacesList)

PrlCreateObject is a function that is called in order to instantiate the corresponding plug-in object. The function should contain a code that will properly initialize and populate the PrlPlugin structure a reference to which is passed back using the Out parameter. The Parallels Service will then use the returned reference to request the necessary interfaces (e.g. PrlCrypt) using the PrlPlugin::QueryInterface() call.

PRL_RESULT PRL_CALL PrlCreateObject(PRL_GUID* Uid, PrlPlugin** Out)

The following subsection provides a sample plug-in implementation.