MdePkg: Add UEFI2.5 Smart Card Reader protocol definitions

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Feng Tian <feng.tian@intel.com>
Reviewed-by: Star Zeng <star.zeng@intel.com>

git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@17293 6f19259b-4bc3-4df7-8a09-765794883524

2 files changed, 329 insertions, 0 deletions

diff --git a/MdePkg/Include/Protocol/SmartCardReader.h b/MdePkg/Include/Protocol/SmartCardReader.h
new file mode 100644
index 0000000000..b093774c01
--- /dev/null
+++ b/MdePkg/Include/Protocol/SmartCardReader.h
@@ -0,0 +1,326 @@
+/** @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
+
diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index 3f5f11f742..f52e5855df 100644
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -1438,6 +1438,9 @@
   ## Include/Protocol/BlockIoCrypto.h

   gEfiBlockIoCryptoProtocolGuid        = { 0xa00490ba, 0x3f1a, 0x4b4c, { 0xab, 0x90, 0x4f, 0xa9, 0x97, 0x26, 0xa1, 0xe8 }}

 

+  ## Include/Protocol/SmartCardReader.h

+  gEfiSmartCardReaderProtocolGuid      = { 0x2a4d1adf, 0x21dc, 0x4b81, {0xa4, 0x2f, 0x8b, 0x8e, 0xe2, 0x38, 0x00, 0x60 }}

+

 #

 # [Error.gEfiMdePkgTokenSpaceGuid]

 #   0x80000001 | Invalid value provided.