+/** @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
+
projects / mirror_edk2.git / commitdiff