3.1.4.1 CreateVirtualSmartCard (Opnum 3)

This method is invoked by the requestor to create a VSC on the target.

 HRESULT CreateVirtualSmartCard(
         [in, string] const wchar_t* pszFriendlyName,
         [in] unsigned char bAdminAlgId,
         [in, size_is(cbAdminKey)] const unsigned char* pbAdminKey,
         [in] unsigned long cbAdminKey,
         [in, unique, size_is(cbAdminKcv)] const unsigned char* pbAdminKcv,
         [in] unsigned long cbAdminKcv,
         [in, unique, size_is(cbPuk)] const unsigned char* pbPuk,
         [in] unsigned long cbPuk,
         [in, size_is(cbPin)] const unsigned char* pbPin,
         [in] unsigned long cbPin,
         [in] int fGenerate,
         [in, unique] ITpmVirtualSmartCardManagerStatusCallback* pStatusCallback,
         [out, string] wchar_t** ppszInstanceId,
         [out] int* pfNeedReboot);
  

pszFriendlyName: A Unicode string for use in any user interface messages relating to this VSC.

bAdminAlgId: An unsigned byte value. This parameter MUST be set to 0x82.

pbAdminKey:  An array of 24 bytes containing a TDEA [SP800-67] key intended to be used as the administrative key for the new VSC.

cbAdminKey: A 32-bit unsigned integer value. It MUST be set to 24.

pbAdminKcv:  An array of bytes containing the Key Check Value (KCV) for the administrative key contained in the pbAdminKey parameter. This parameter is optional and MUST be set to NULL if absent. If present, it MUST be computed by encrypting eight zero bytes using the TDEA [SP800-67] block cipher and taking the first three bytes.

cbAdminKcv: A 32-bit unsigned integer value. It MUST be set to 0 if the pbAdmin parameter is NULL, and MUST be set to 3 otherwise.

pbPuk:  An array of bytes containing the desired PUK for the new VSC. This parameter is optional and MUST be set to NULL if absent. If present, its length MUST be between 8 and 127 bytes, inclusive.

cbPuk: A 32-bit unsigned integer value. It MUST be equal to the length of the pbPuk parameter in bytes. If pbPuk is NULL, this parameter MUST be set to 0.

pbPin: An array of bytes containing the desired PIN for the new VSC. Its length MUST be between 8 and 127 bytes, inclusive.

cbPin: A 32-bit unsigned integer value. It MUST be equal to the length of the pbPin parameter in bytes.

fGenerate: A Boolean value that indicates whether a file system is to be generated on the new VSC.

pStatusCallback: A reference to an instance of the ITpmVirtualSmartCardManagerStatusCallback DCOM interface on the requestor. The server uses this interface to provide feedback on progress and errors. This parameter is optional and MUST be set to NULL if absent.

ppszInstanceId: A Unicode string containing a unique instance identifier for the VSC created by this operation.

pfNeedReboot: A Boolean value that indicates whether or not a reboot is required on the server before the newly-created VSC is made available to applications.

Return Values: The server MUST return 0 if it successfully creates the new VSC, and a nonzero value otherwise.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

The server MUST validate the parameters before executing the requested operation and fail requests with invalid parameters.

If pbAdminKcv is present, the server MUST perform admin key integrity check. The admin key integrity check is done by encrypting eight zero bytes using the TDEA [SP800-67] block cipher, taking the first 3 bytes and verifying that it matches the provided pbAdminKcv value. If the computed bytes do not match the provided pbAdminKcv value, the admin key integrity check fails and the server MUST fail the requested operation.

If pbPuk is present, the server MUST create a VSC that supports PUK-based PIN reset and its PUK is set as the provided pbPuk value. Otherwise, the server MUST create a VSC that supports challenge-response-based PIN reset through the admin role.

Upon successful creation of a VSC, the server MUST initialize all data structures necessary for the VSC, and register it with the underlying smart card implementation compliant with [PCSC3]. The server MUST allocate an instance identifier to the newly-created VSC that is unique among all such identifiers in use at that time.

If pStatusCallback is present, the server SHOULD notify the client of the progress and errors of the undergoing operation, as specified in section 3.2.4. The status callback happens synchronously with the requested operation. If the status callback returns an error code, the server MUST abort the VSC creation and return a non-zero error to the client, with the severity bit in the error code set to 1. In this case, the server SHOULD also roll back all changes made in respect to the requested operation.