3.3.4.1 CreateVirtualSmartCardWithPinPolicy (Opnum 5)

This method is invoked by the requestor to create a VSC with the specified PIN policy on the target.

 HRESULT CreateVirtualSmartCardWithPinPolicy(
         [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, unique, size_is(cbPinPolicy)] const unsigned char* pbPinPolicy,
         [in] unsigned long cbPinPolicy,
         [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 4 and 127 bytes, inclusive.

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

pbPinPolicy:  A PinPolicySerialization structure specifying the PIN policy for the new VSC, as described in section 2.2.2.1.

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

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, using the validation rules specified in section 3.1.4.1, and fail requests with invalid parameters.

If pbPinPolicy is present, the server MUST validate that it is exactly 32 bytes in size and conforms to the format specified in section 2.2.2.1. The server MUST fail the requested operation if any of the following is true:

  • minLength is not between 4 and 127, inclusive.

  • maxLength is not between 4 and 127, inclusive.

  • maxLength is not greater than or equal to minLength.

  • The value of uppercaseLettersPolicyOption is not a valid member of the SmartCardPinCharacterPolicyOption enumerated type.

  • The value of lowercaseLettersPolicyOption is not a valid member of the SmartCardPinCharacterPolicyOption enumerated type.

  • The value of digitsPolicyOption is not a valid member of the SmartCardPinCharacterPolicyOption enumerated type.

  • The value of specialCharactersPolicyOption is not a valid member of the SmartCardPinCharacterPolicyOption enumerated type

  • The value of otherCharactersPolicyOption is not a valid member of the SmartCardPinCharacterPolicyOption enumerated type

After validating these conditions, the server MUST proceed to create the VSC and notify the client of progress through the callback interface as specified in section 3.1.4.1. The server MUST also initialize the appropriate data structures for the VSC in accordance with the PIN policy specified by the caller.