CardGetSharedKeyHandle function

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

Syntax

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

Parameters

• 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.

Remarks

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.

Requirements

Send comments about this topic to Microsoft