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