You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
326 lines
15 KiB
326 lines
15 KiB
4 years ago
|
/** @file
|
||
|
|
The UEFI Smart Card Reader Protocol provides an abstraction for device to provide
|
||
|
|
smart card reader support. This protocol is very close to Part 5 of PC/SC workgroup
|
||
|
|
specifications and provides an API to applications willing to communicate with a
|
||
|
|
smart card or a smart card reader.
|
||
|
|
|
||
|
|
Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
|
||
|
|
This program and the accompanying materials
|
||
|
|
are licensed and made available under the terms and conditions of the BSD License
|
||
|
|
which accompanies this distribution. The full text of the license may be found at
|
||
|
|
http://opensource.org/licenses/bsd-license.php
|
||
|
|
|
||
|
|
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
|
||
|
|
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
|
||
|
|
|
||
|
|
**/
|
||
|
|
|
||
|
|
#ifndef __SMART_CARD_READER_H__
|
||
|
|
#define __SMART_CARD_READER_H__
|
||
|
|
|
||
|
|
#define EFI_SMART_CARD_READER_PROTOCOL_GUID \
|
||
|
|
{ \
|
||
|
|
0x2a4d1adf, 0x21dc, 0x4b81, {0xa4, 0x2f, 0x8b, 0x8e, 0xe2, 0x38, 0x00, 0x60} \
|
||
|
|
}
|
||
|
|
|
||
|
|
typedef struct _EFI_SMART_CARD_READER_PROTOCOL EFI_SMART_CARD_READER_PROTOCOL;
|
||
|
|
|
||
|
|
//
|
||
|
|
// Codes for access mode
|
||
|
|
//
|
||
|
|
#define SCARD_AM_READER 0x0001 // Exclusive access to reader
|
||
|
|
#define SCARD_AM_CARD 0x0002 // Exclusive access to card
|
||
|
|
//
|
||
|
|
// Codes for card action
|
||
|
|
//
|
||
|
|
#define SCARD_CA_NORESET 0x0000 // Don't reset card
|
||
|
|
#define SCARD_CA_COLDRESET 0x0001 // Perform a cold reset
|
||
|
|
#define SCARD_CA_WARMRESET 0x0002 // Perform a warm reset
|
||
|
|
#define SCARD_CA_UNPOWER 0x0003 // Power off the card
|
||
|
|
#define SCARD_CA_EJECT 0x0004 // Eject the card
|
||
|
|
//
|
||
|
|
// Protocol types
|
||
|
|
//
|
||
|
|
#define SCARD_PROTOCOL_UNDEFINED 0x0000
|
||
|
|
#define SCARD_PROTOCOL_T0 0x0001
|
||
|
|
#define SCARD_PROTOCOL_T1 0x0002
|
||
|
|
#define SCARD_PROTOCOL_RAW 0x0004
|
||
|
|
//
|
||
|
|
// Codes for state type
|
||
|
|
//
|
||
|
|
#define SCARD_UNKNOWN 0x0000 /* state is unknown */
|
||
|
|
#define SCARD_ABSENT 0x0001 /* Card is absent */
|
||
|
|
#define SCARD_INACTIVE 0x0002 /* Card is present and not powered*/
|
||
|
|
#define SCARD_ACTIVE 0x0003 /* Card is present and powered */
|
||
|
|
//
|
||
|
|
// Macro to generate a ControlCode & PC/SC part 10 control code
|
||
|
|
//
|
||
|
|
#define SCARD_CTL_CODE(code) (0x42000000 + (code))
|
||
|
|
#define CM_IOCTL_GET_FEATURE_REQUEST SCARD_CTL_CODE(3400)
|
||
|
|
|
||
|
|
/**
|
||
|
|
This function requests connection to the smart card or the reader, using the
|
||
|
|
appropriate reset type and protocol.
|
||
|
|
|
||
|
|
The SCardConnectfunction requests access to the smart card or the reader. Upon
|
||
|
|
success, it is then possible to call SCardTransmit.
|
||
|
|
|
||
|
|
If AccessMode is set to SCARD_AM_READER, PreferredProtocols must be set to
|
||
|
|
SCARD_PROTOCOL_UNDEFINED and CardAction to SCARD_CA_NORESET else function
|
||
|
|
fails with EFI_INVALID_PARAMETER.
|
||
|
|
|
||
|
|
@param[in] This Indicates a pointer to the calling context.
|
||
|
|
@param[in] AccessMode Codes of access mode.
|
||
|
|
@param[in] CardAction SCARD_CA_NORESET, SCARD_CA_COLDRESET or
|
||
|
|
SCARD_CA_WARMRESET.
|
||
|
|
@param[in] PreferredProtocols Bitmask of acceptable protocols.
|
||
|
|
@param[out] ActiveProtocol A flag that indicates the active protocol.
|
||
|
|
|
||
|
|
@retval EFI_SUCCESS The requested command completed successfully.
|
||
|
|
@retval EFI_INVALID_PARAMETER This is NULL
|
||
|
|
@retval EFI_INVALID_PARAMETER AccessMode is not valid.
|
||
|
|
@retval EFI_INVALID_PARAMETER CardAction is not valid.
|
||
|
|
@retval EFI_INVALID_PARAMETER Invalid combination of AccessMode/CardAction/
|
||
|
|
PreferredProtocols.
|
||
|
|
@retval EFI_NOT_READY A smart card is inserted but failed to return an ATR.
|
||
|
|
@retval EFI_UNSUPPORTED PreferredProtocols does not contain an available
|
||
|
|
protocol to use.
|
||
|
|
@retval EFI_NO_MEDIA AccessMode is set to SCARD_AM_CARD but there is
|
||
|
|
no smart card inserted.
|
||
|
|
@retval EFI_ACCESS_DENIED Access is already locked by a previous SCardConnectcall.
|
||
|
|
@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
|
||
|
|
|
||
|
|
**/
|
||
|
|
typedef
|
||
|
|
EFI_STATUS
|
||
|
|
(EFIAPI *EFI_SMART_CARD_READER_CONNECT) (
|
||
|
|
IN EFI_SMART_CARD_READER_PROTOCOL *This,
|
||
|
|
IN UINT32 AccessMode,
|
||
|
|
IN UINT32 CardAction,
|
||
|
|
IN UINT32 PreferredProtocols,
|
||
|
|
OUT UINT32 *ActiveProtocol
|
||
|
|
);
|
||
|
|
|
||
|
|
/**
|
||
|
|
This function releases a connection previously taken by SCardConnect.
|
||
|
|
|
||
|
|
The SCardDisconnect function releases the lock previously taken by SCardConnect.
|
||
|
|
In case the smart card has been removed before this call, thisfunction
|
||
|
|
returns EFI_SUCCESS. If there is no previous call to SCardConnect, this
|
||
|
|
function returns EFI_SUCCESS.
|
||
|
|
|
||
|
|
@param[in] This Indicates a pointer to the calling context.
|
||
|
|
@param[in] CardAction Codes for card action.
|
||
|
|
|
||
|
|
@retval EFI_SUCCESS The requested command completed successfully.
|
||
|
|
@retval EFI_INVALID_PARAMETER This is NULL
|
||
|
|
@retval EFI_INVALID_PARAMETER CardAction value is unknown.
|
||
|
|
@retval EFI_UNSUPPORTED Reader does not support Eject card feature
|
||
|
|
(disconnect was not performed).
|
||
|
|
@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
|
||
|
|
|
||
|
|
**/
|
||
|
|
typedef
|
||
|
|
EFI_STATUS
|
||
|
|
(EFIAPI *EFI_SMART_CARD_READER_DISCONNECT) (
|
||
|
|
IN EFI_SMART_CARD_READER_PROTOCOL *This,
|
||
|
|
IN UINT32 CardAction
|
||
|
|
);
|
||
|
|
|
||
|
|
/**
|
||
|
|
This function retrieves some basic information about the smart card and reader.
|
||
|
|
|
||
|
|
The SCardStatusfunction retrieves basic reader and card information.
|
||
|
|
|
||
|
|
If ReaderName, State, CardProtocolor Atris NULL, the function does not fail but
|
||
|
|
does not fill in such variables.
|
||
|
|
|
||
|
|
If EFI_SUCCESS is not returned, ReaderName and Atr contents shall not be considered
|
||
|
|
as valid.
|
||
|
|
|
||
|
|
@param[in] This Indicates a pointer to the calling context.
|
||
|
|
@param[out] ReaderName A pointer to a NULL terminated string that will
|
||
|
|
contain the reader name.
|
||
|
|
@param[in, out] ReaderNameLength On input, a pointer to the variablethat holds the
|
||
|
|
maximal size, in bytes,of ReaderName.
|
||
|
|
On output, the required size, in bytes, for ReaderName.
|
||
|
|
@param[out] State Current state of the smart card reader.
|
||
|
|
@param[out] CardProtocol Current protocol used to communicate with the smart card.
|
||
|
|
@param[out] Atr A pointer to retrieve the ATR of the smart card.
|
||
|
|
@param[in, out] AtrLength On input, a pointer to hold the maximum size, in bytes,
|
||
|
|
of Atr(usually 33).
|
||
|
|
On output, the required size, inbytes, for the smart
|
||
|
|
card ATR.
|
||
|
|
|
||
|
|
@retval EFI_SUCCESS The requested command completed successfully.
|
||
|
|
@retval EFI_INVALID_PARAMETER This is NULL
|
||
|
|
@retval EFI_INVALID_PARAMETER ReaderName is not NULL but ReaderNameLength is NULL
|
||
|
|
@retval EFI_INVALID_PARAMETER Atr is not NULL but AtrLength is NULL
|
||
|
|
@retval EFI_BUFFER_TOO_SMALL ReaderNameLength is not big enough to hold the reader name.
|
||
|
|
ReaderNameLength has been updated to the required value.
|
||
|
|
@retval EFI_BUFFER_TOO_SMALL AtrLength is not big enough to hold the ATR.
|
||
|
|
AtrLength has been updated to the required value.
|
||
|
|
@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
|
||
|
|
|
||
|
|
**/
|
||
|
|
typedef
|
||
|
|
EFI_STATUS
|
||
|
|
(EFIAPI *EFI_SMART_CARD_READER_STATUS) (
|
||
|
|
IN EFI_SMART_CARD_READER_PROTOCOL *This,
|
||
|
|
OUT CHAR16 *ReaderName OPTIONAL,
|
||
|
|
IN OUT UINTN *ReaderNameLength OPTIONAL,
|
||
|
|
OUT UINT32 *State OPTIONAL,
|
||
|
|
OUT UINT32 *CardProtocol OPTIONAL,
|
||
|
|
OUT UINT8 *Atr OPTIONAL,
|
||
|
|
IN OUT UINTN *AtrLength OPTIONAL
|
||
|
|
);
|
||
|
|
|
||
|
|
/**
|
||
|
|
This function sends a command to the card or reader and returns its response.
|
||
|
|
|
||
|
|
The protocol to use to communicate with the smart card has been selected through
|
||
|
|
SCardConnectcall.
|
||
|
|
|
||
|
|
In case RAPDULength indicates a buffer too small to holdthe response APDU, the
|
||
|
|
function fails with EFI_BUFFER_TOO_SMALL.
|
||
|
|
|
||
|
|
@param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance.
|
||
|
|
@param[in] CAPDU A pointer to a byte array thatcontains the Command
|
||
|
|
APDU to send to the smart card or reader.
|
||
|
|
@param[in] CAPDULength Command APDU size, in bytes.
|
||
|
|
@param[out] RAPDU A pointer to a byte array that will contain the
|
||
|
|
Response APDU.
|
||
|
|
@param[in, out] RAPDULength On input, the maximum size, inbytes, of the Response
|
||
|
|
APDU.
|
||
|
|
On output, the size, in bytes, of the Response APDU.
|
||
|
|
|
||
|
|
@retval EFI_SUCCESS The requested command completed successfully.
|
||
|
|
@retval EFI_INVALID_PARAMETER This is NULL.
|
||
|
|
@retval EFI_INVALID_PARAMETER CAPDU is NULL or CAPDULength is 0.
|
||
|
|
@retval EFI_BUFFER_TOO_SMALL RAPDULength is not big enough to hold the response APDU.
|
||
|
|
RAPDULength has been updated to the required value.
|
||
|
|
@retval EFI_NO_MEDIA There is no card in the reader.
|
||
|
|
@retval EFI_NOT_READY Card is not powered.
|
||
|
|
@retval EFI_PROTOCOL_ERROR A protocol error has occurred.
|
||
|
|
@retval EFI_TIMEOUT The reader did not respond.
|
||
|
|
@retval EFI_ACCESS_DENIED A communication with the reader/card is already pending.
|
||
|
|
@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
|
||
|
|
|
||
|
|
**/
|
||
|
|
typedef
|
||
|
|
EFI_STATUS
|
||
|
|
(EFIAPI *EFI_SMART_CARD_READER_TRANSMIT) (
|
||
|
|
IN EFI_SMART_CARD_READER_PROTOCOL *This,
|
||
|
|
IN UINT8 *CAPDU,
|
||
|
|
IN UINTN CAPDULength,
|
||
|
|
OUT UINT8 *RAPDU,
|
||
|
|
IN OUT UINTN *RAPDULength
|
||
|
|
);
|
||
|
|
|
||
|
|
/**
|
||
|
|
This function provides direct access to the reader.
|
||
|
|
|
||
|
|
This function gives direct control to send commands to the driver or the reader.
|
||
|
|
The ControlCode to use is vendor dependant; the only standard code defined is
|
||
|
|
the one to get PC/SC part 10 features.
|
||
|
|
|
||
|
|
InBuffer and Outbuffer may be NULL when ControlCode operation does not require
|
||
|
|
them.
|
||
|
|
|
||
|
|
@param[in] This Indicates a pointer to the calling context.
|
||
|
|
@param[in] ControlCode The control code for the operation to perform.
|
||
|
|
@param[in] InBuffer A pointer to the input parameters.
|
||
|
|
@param[in] InBufferLength Size, in bytes, of input parameters.
|
||
|
|
@param[out] OutBuffer A pointer to the output parameters.
|
||
|
|
@param[in, out] OutBufferLength On input, maximal size, in bytes, to store output
|
||
|
|
parameters.
|
||
|
|
On output, the size, in bytes, of output parameters.
|
||
|
|
|
||
|
|
@retval EFI_SUCCESS The requested command completed successfully.
|
||
|
|
@retval EFI_INVALID_PARAMETER This is NULL.
|
||
|
|
@retval EFI_INVALID_PARAMETER ControlCode requires input parameters but:
|
||
|
|
InBuffer is NULL or InBufferLenth is NULL or
|
||
|
|
InBuffer is not NULL but InBufferLenth is less than
|
||
|
|
expected.
|
||
|
|
@retval EFI_INVALID_PARAMETER OutBuffer is not NULL but OutBufferLength is NULL.
|
||
|
|
@retval EFI_UNSUPPORTED ControlCode is not supported.
|
||
|
|
@retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output
|
||
|
|
parameters.
|
||
|
|
OutBufferLength has been updated to the required value.
|
||
|
|
@retval EFI_NO_MEDIA There is no card in the reader and the control code
|
||
|
|
specified requires one.
|
||
|
|
@retval EFI_NOT_READY ControlCode requires a powered card to operate.
|
||
|
|
@retval EFI_PROTOCOL_ERROR A protocol error has occurred.
|
||
|
|
@retval EFI_TIMEOUT The reader did not respond.
|
||
|
|
@retval EFI_ACCESS_DENIED A communication with the reader/card is already pending.
|
||
|
|
@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
|
||
|
|
|
||
|
|
**/
|
||
|
|
typedef
|
||
|
|
EFI_STATUS
|
||
|
|
(EFIAPI *EFI_SMART_CARD_READER_CONTROL) (
|
||
|
|
IN EFI_SMART_CARD_READER_PROTOCOL *This,
|
||
|
|
IN UINT32 ControlCode,
|
||
|
|
IN UINT8 *InBuffer OPTIONAL,
|
||
|
|
IN UINTN InBufferLength OPTIONAL,
|
||
|
|
OUT UINT8 *OutBuffer OPTIONAL,
|
||
|
|
IN OUT UINTN *OutBufferLength OPTIONAL
|
||
|
|
);
|
||
|
|
|
||
|
|
/**
|
||
|
|
This function retrieves a reader or smart card attribute.
|
||
|
|
|
||
|
|
Possibly supported attrib values are listed in "PC/SC specification, Part 3:
|
||
|
|
Requirements for PC-Connected Interface Devices".
|
||
|
|
|
||
|
|
@param[in] This Indicates a pointer to the calling context.
|
||
|
|
@param[in] Attrib Identifier for the attribute to retrieve.
|
||
|
|
@param[out] OutBuffer A pointer to a buffer that will contain
|
||
|
|
attribute data.
|
||
|
|
@param[in, out] OutBufferLength On input, maximal size, in bytes, to store
|
||
|
|
attribute data.
|
||
|
|
On output, the size, in bytes, of attribute
|
||
|
|
data.
|
||
|
|
|
||
|
|
@retval EFI_SUCCESS The requested command completed successfully.
|
||
|
|
@retval EFI_INVALID_PARAMETER This is NULL.
|
||
|
|
@retval EFI_INVALID_PARAMETER OutBuffer is NULL or OutBufferLength is 0.
|
||
|
|
@retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output
|
||
|
|
parameters.
|
||
|
|
OutBufferLength has been updated to the required value.
|
||
|
|
@retval EFI_UNSUPPORTED Attribis not supported
|
||
|
|
@retval EFI_NO_MEDIA There is no card in the reader and Attrib value
|
||
|
|
requires one.
|
||
|
|
@retval EFI_NOT_READY Attrib requires a powered card to operate.
|
||
|
|
@retval EFI_PROTOCOL_ERROR A protocol error has occurred.
|
||
|
|
@retval EFI_TIMEOUT The reader did not respond.
|
||
|
|
@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
|
||
|
|
|
||
|
|
**/
|
||
|
|
typedef
|
||
|
|
EFI_STATUS
|
||
|
|
(EFIAPI *EFI_SMART_CARD_READER_GET_ATTRIB) (
|
||
|
|
IN EFI_SMART_CARD_READER_PROTOCOL *This,
|
||
|
|
IN UINT32 Attrib,
|
||
|
|
OUT UINT8 *OutBuffer,
|
||
|
|
IN OUT UINTN *OutBufferLength
|
||
|
|
);
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Smart card aware application invokes this protocol to get access to an inserted
|
||
|
|
/// smart card in the reader or to the reader itself.
|
||
|
|
///
|
||
|
|
struct _EFI_SMART_CARD_READER_PROTOCOL {
|
||
|
|
EFI_SMART_CARD_READER_CONNECT SCardConnect;
|
||
|
|
EFI_SMART_CARD_READER_DISCONNECT SCardDisconnect;
|
||
|
|
EFI_SMART_CARD_READER_STATUS SCardStatus;
|
||
|
|
EFI_SMART_CARD_READER_TRANSMIT SCardTransmit;
|
||
|
|
EFI_SMART_CARD_READER_CONTROL SCardControl;
|
||
|
|
EFI_SMART_CARD_READER_GET_ATTRIB SCardGetAttrib;
|
||
|
|
};
|
||
|
|
|
||
|
|
extern EFI_GUID gEfiSmartCardReaderProtocolGuid;
|
||
|
|
|
||
|
|
#endif
|
||
|
|
|