Important!

Blog moved to https://blog.apdu.fr/

I moved my blog from https://ludovicrousseau.blogspot.com/ to https://blog.apdu.fr/ . Why? I wanted to move away from Blogger (owne...

Wednesday, May 27, 2015

PCSC sample in C for UEFI

To continue the list of PC/SC wrappers initiated more than four years ago with "PC/SC sample in different languages" I now present a PC/SC sample written in C but for UEFI.

UEFI

UEFI stands for Unified Extensible Firmware Interface. UEFI is an evolution of EFI. EFI should replace BIOS on "modern" "Intel PC" computers.

Any 64-bits Intel (or compatible) PC computer should have UEFI (and maybe also a BIOS for compatibility).

See my previous article "UEFI Smart Card Reader Protocol" for some more details.

Sample source code

#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Library/ShellCEntryLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/BaseMemoryLib.h>

#include <Protocol/SmartCardReader.h>

int HelloWorld(EFI_SMART_CARD_READER_PROTOCOL *SmartCardReader)
{
    EFI_STATUS  Status;
    UINT32 ActiveProtocol;
    int i;
    UINT8 CAPDU_select[] = {0x00, 0xA4, 0x04, 0x00, 0x0A, 0xA0, 0x00, 0x00, 0x00, 0x62, 0x03, 0x01, 0x0C, 0x06, 0x01};
    UINT8 CAPDU_command[] = {0x00, 0x00, 0x00, 0x00};
    UINTN CAPDULength, RAPDULength;
    UINT8 RAPDU[256+2];

    /*
     * SCardConnect
     */
    Status = SmartCardReader->SCardConnect(SmartCardReader,
        SCARD_AM_CARD,
        SCARD_CA_COLDRESET,
        SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
        &ActiveProtocol);
    if (EFI_ERROR(Status))
    {
        Print(L"ERROR: SCardConnect: %d\n", Status);
        return 0;
    }

    /*
     * SCardTransmit Select
     */
    CAPDULength = sizeof CAPDU_select;
    RAPDULength = sizeof RAPDU;
    Status = SmartCardReader->SCardTransmit(SmartCardReader,
        CAPDU_select, CAPDULength,
        RAPDU, &RAPDULength);
    if (EFI_ERROR(Status))
    {
        Print(L"ERROR: SCardTransmit: %d\n", Status);
        return 0;
    }
    Print(L"RAPDU: ");
    for (i=0; i<RAPDULength; i++)
        Print(L"%02X ", RAPDU[i]);
    Print(L"\n");

    /*
     * SCardTransmit Command
     */
    CAPDULength = sizeof CAPDU_command;
    RAPDULength = sizeof RAPDU;
    Status = SmartCardReader->SCardTransmit(SmartCardReader,
        CAPDU_command, CAPDULength,
        RAPDU, &RAPDULength);
    if (EFI_ERROR(Status))
    {
        Print(L"ERROR: SCardTransmit: %d\n", Status);
        return 0;
    }
    Print(L"RAPDU: ");
    for (i=0; i<RAPDULength; i++)
        Print(L"%02X ", RAPDU[i]);
    Print(L"\n");
    for (i=0; i<RAPDULength; i++)
        Print(L"%c", RAPDU[i]);
    Print(L"\n");

    /*
     * SCardDisconnect
     */
    Status = SmartCardReader->SCardDisconnect(SmartCardReader,
        SCARD_CA_NORESET);
    if (EFI_ERROR(Status))
    {
        Print(L"ERROR: SCardDisconnect: %d\n", Status);
        return 0;
    }

    return 0;
}

INTN
EFIAPI
ShellAppMain (
  IN UINTN Argc,
  IN CHAR16 **Argv
  )
{
    EFI_STATUS  Status;
    UINTN       HandleIndex, HandleCount;
    EFI_HANDLE  *DevicePathHandleBuffer = NULL;
    EFI_SMART_CARD_READER_PROTOCOL *SmartCardReader;

    /* EFI_SMART_CARD_READER_PROTOCOL */
    Status = gBS->LocateHandleBuffer(
            ByProtocol,
            &gEfiSmartCardReaderProtocolGuid,
            NULL,
            &HandleCount,
            &DevicePathHandleBuffer);

    if (EFI_ERROR(Status))
    {
        Print(L"ERROR: Get EFI_SMART_CARD_READER_PROTOCOL count fail.\n");
        return 0;
    }

    Print(L"Found %d reader(s)\n", HandleCount);
    for (HandleIndex = 0; HandleIndex < HandleCount; HandleIndex++)
    {
        ZeroMem(&SmartCardReader, sizeof SmartCardReader);

        Status = gBS->HandleProtocol(
                DevicePathHandleBuffer[HandleIndex],
                &gEfiSmartCardReaderProtocolGuid,
                (VOID**)&SmartCardReader);

        if (EFI_ERROR(Status))
        {
            Print(L"ERROR: Open Protocol fail.\n");
            gBS->FreePool(DevicePathHandleBuffer);
            return 0;
        }

        HelloWorld(SmartCardReader);
    }
    gBS->FreePool(DevicePathHandleBuffer);

    return(0);
}

Output

Found 1 reader(s)
RAPDU: 90 00 
RAPDU: 48 65 6C 6C 6F 20 77 6F 72 6C 64 21 90 00 
Hello world!

Test platform

I used a Dell laptop model E6420 (shipped in August 2013) with an integrated Broadcom smart card reader. This reader was already in the "should work" list of my CCID driver. Of course the SmartCardReader API was not included in the UEFI. I had to write the driver myself.

I made tests with older Dell laptops and had problems with the USB UEFI layer. It looks like UEFI is still a work in progress and bugs/limitations are common.

I started by using a software simulator qemu + UEFI but I could not use a USB device with the simulator. So I rapidly had to use a real hardware. Developing a UEFI driver involves a lot of reboot to try a new version of the driver.

Remarks

I added error checks and logging feature in the source code.

The API is not high level but mostly the direct equivalent of WinSCard (the classic C API for smart cards).

Conclusion

It was fun to work on UEFI and learn a new technology.

UEFI is very powerful. Time will tell if the SmartCardReader API will be deployed and used.

UEFI Smart Card Reader Protocol

The release 2.5, April 2015 of the Unified Extensible Firmware Interface Specification (UEFI) contains 2 new protocols:
  • Smart Card Reader Protocol
  • Smart Card Edge Protocol

The specification is available in at http://www.uefi.org/sites/default/files/resources/UEFI%202_5.pdf from the UEFI web site.

Smart Card Reader Protocol

The Smart Card Reader Protocol is described in chapter 35.6.1 page 2241 (yes, the specification is one huge document of 14 MB and 2588 pages).

The functions provided are:
typedef 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;
} EFI_SMART_CARD_READER_PROTOCOL;

You may be surprised that there is no function to list the available readers. This is because UEFI has its own way to enumerate resources. Each smart card reader will have its own EFI_SMART_CARD_READER_PROTOCOL structure. The program just have to iterate over all the protocols identified as EFI_SMART_CARD_READER_PROTOCOL_GUID.

Usage

The planned usage of the Smart Card Reader Protocol is to be used from an UEFI application so before the operating system (Windows, GNU/Linux, Mac OS X, etc.) is started.
This can be used to access a smart card and get a secret key from the smart card after a PIN has been verified. The secret key could be used to decipher the hard disk.

Smart Card Edge Protocol

The Smart Card Edge Protocol is described in chapter 35.6.2 page 2253.

The functions provided are:
typedef struct _EFI_SMART_CARD_EDGE_PROTOCOL {
 EFI_SMART_CARD_EDGE_GET_CONTEXT        GetContext;
 EFI_SMART_CARD_EDGE_CONNECT            Connect;
 EFI_SMART_CARD_EDGE_DISCONNECT         Disconnect;
 EFI_SMART_CARD_EDGE_GET_CSN            GetCsn;
 EFI_SMART_CARD_EDGE_GET_READER_NAME    GetReaderName;
 EFI_SMART_CARD_EDGE_VERIFY_PIN         VerifyPin;
 EFI_SMART_CARD_EDGE_GET_PIN_REMAINING  GetPinRemaining;
 EFI_SMART_CARD_EDGE_GET_DATA           GetData;
 EFI_SMART_CARD_EDGE_GET_CREDENTIAL     GetCredential;
 EFI_SMART_CARD_EDGE_SIGN_DATA          SignData;
 EFI_SMART_CARD_EDGE_DECRYPT_DATA       DecryptData;
 EFI_SMART_CARD_EDGE_BUILD_DH_AGREEMENT BuildDHAgreement;
} EFI_SMART_CARD_EDGE_PROTOCOL;

Usage

This API allows to easily use a PKI card. It is the same idea as a PKCS#11 or MiniDriver library: abstract the smart card specificities and make an UEFI application able to use different PKI smart cards without writing specific source code.

Can I use it now?

The specification is now public. You can implement it yourself and play with it. Or you can wait for someone else to implement it and provide it in the UEFI of your next computer.

I already implemented the Smart Card Reader Protocol. I will proposed it for inclusion to TianoCore.

Conclusion

Stay tuned. Do not expect to have it included in the UEFI of your next computer before some time.

But if you are a developer you can play with it now.

Wednesday, May 13, 2015

New version of libccid: 1.4.19

I just released a version 1.4.19 of libccid the free software CCID class smart card reader driver.

Direct download here.

Changes:
1.4.19 - 13 May 2014, Ludovic Rousseau
  • Add support of
    • AK910 CKey (idProduct 0x0001)
    • AK910 CKey (idProduct 0x0011)
    • AK910 IDONE
    • Broadcom Corp 5880 (idProduct: 0x5804)
    • CASTLES EZCCID Smart Card Reader
    • Cherry KC 1000 SC
    • Cherry KC 1000 SC Z
    • Cherry KC 1000 SC/DI
    • Cherry KC 1000 SC/DI Z
    • Cherry TC 1300
    • Chicony USB Smart Card Keyboard
    • Elatec TWN4 SmartCard NFC
    • Feitian 502-CL
    • Feitian eJAVA Token
    • FujitsuTechnologySolutions GmbH Keyboard KB100 SCR
    • FujitsuTechnologySolutions GmbH Keyboard KB100 SCR eSIG
    • Hewlett-Packard HP lt4112 Gobi 4G Module
    • Identive SCT3522CC token
    • OMNIKEY AG 6121 USB mobile
    • PIVKey T800
    • REINER SCT tanJack Bluetooth
    • Watchdata USB Key
  • Add syslog(3) debug for Mac OS X Yosemite.
    Use: sudo syslog -c "com.apple.ifdreader PID" -d to change the logging level.
    See also "Change syslog logging level on Yosemite" http://ludovicrousseau.blogspot.com/2015/03/change-syslog-logging-level-on-yosemite.html
  • Remove ZLP patch for Gemalto IDBridge CT30 and K30. The patch was causing problems with the K50. A new reader firmware (version F) solved the problem so the patch is no more needed.
  • Fix a memory leak in an error path
  • some minor bugs removed