CardGetSharedKeyHandle function

The CardGetSharedKeyHandle function returns a session key handle to the caller.


DWORD WINAPI CardGetSharedKeyHandle(
  _In_       PCARD_DATA pCardData,
  _In_       PBYTE pbInput,
  _In_       DWORD cbInput,
  _Out_opt_  PBYTE *ppbOutput,
  _Out_opt_  PDWORD pcbOutput,
  _Out_      PCARD_KEY_HANDLE phKey


pCardData [in]

Context information for the call. For more information, see CardAcquireContext.

pbInput [in]

A byte pointer to the optional data buffer that contains the input data.

cbInput [in]

The length, in bytes, of the optional data buffer.

ppbOutput [out, optional]

A byte pointer to the optional data buffer that receives the potential data that is returned from the minidriver. The data buffer is allocated by the minidriver and freed by the caller.

pcbOutput [out, optional]

An optional pointer to a value that receives the actual data length that is returned in ppbOutput.

phKey [out]

A pointer to a CARD_KEY_HANDLE. This handle is used in subsequent functions that require the key, such as CardProcessEncryptedData. The handle must be released when it is no longer needed by calling CardDestroyKey.

Return value

Zero on success; otherwise, nonzero.


Note  The manner in which this session key has been established is outside the scope of this specification. For example, the session key could be established by either a permanent shared key or a key derivation algorithm that has occurred before the call to CardGetSharedKeyHandle.

If the card minidriver does not support the return of shared key handles, the function should return SCARD_E_UNSUPPORTED_FEATURE.

The optional input (pbInput) and output (ppbOutput) data buffers can be used to provide key derivation data to and from the minidriver. For example, this would work well with a key establishment protocol, such as the protocol that is specified by GlobalPlatform.

If the phKey parameter is NULL or does not contain a valid pointer, the function should return SCARD_E_INVALID_PARAMETER.

If this function succeeds, the phKey parameter should hold one of the following values:

  • A NULL value, which indicates that the key establishment protocol has not completed. In this situation, the minidriver requires another round trip of data before it can establish the shared key. For example, this could be used with the optional input/output buffers as part of a key derivation algorithm.
  • A handle to the shared key after the key establishment protocol is complete.

The key is expected to be valid until CardDestroyKey is called or the card is removed from the reader.

The context of this key handle is determined by whether the CARD_SECURE_KEY_INJECTION_NO_CARD_MODE flag was set in the dwFlags parameter when CardAcquireContext was called. If this flag was not set, the key handle translates to a key on the card. If this flag was set, the key handle might be a handle to a predefined key on the server.



Cardmod.h (include Cardmod.h)



Send comments about this topic to Microsoft

© 2014 Microsoft