Smart Cards in .NET, Part 2

Today, learn the basics of writing a pure managed wrapper for Smart Cards on the WinSCard API using interop to accomplish this.


A Support File for this article is available here.


In the previous article of this series we had an introduction to the smart card standards and the PC/SC specification. We also accessed the Smart Card using the Smart Card API. To access Smart Cards in .NET we made a COM Component and accessed the Smart Card in .NET with its help.

In this article we’ll see the basics for writing a pure managed wrapper on the WinSCard API and write a sample program to do so. Along the way I’ll explain to you the basics of interop by means of which we’ll accomplish all of the aforementioned things. These concepts are general and can be applied not only to this problem, but any problem where one needs to access the native Win32 API from within the .NET framework.

How to approach

One can approach the problem of accessing Smart Card in .NET in many ways. We already discussed one way in the last article. Now we’ll try accessing the WinSCard API directly without involving any of the COM and Runtime Callable Wrappers we used in that case.

In this case, we’ll use the Platform Invoke services of the .NET framework and access the Smart Card API directly from our C# or VB .Net code. Let’s take a quick look at the basics of using the Interop services before we move into the details of writing a managed wrapper on the whole Smart Card API.

{mospagebreak title=The Basics}

DLLs in the native world contain just the code and no metadata, except for the related exports in one of the tables in the PE Image. But how would the .NET runtime be able to get all the information about the function in a DLL, or the data or inputs .NET expects us to pass to it? Moreover, .NET will need to know whether data is to be returned from the called native function and what kind of data it is. Anyone programming in .NET would be aware of the differences in types in the Managed and Unmanaged world.

The Platform Invoke or the P/Invoke uses the metadata that we provide in our managed code to locate exported functions and marshal their arguments at run time. The following illustration shows this process.

Smart Cards in .NET Part 2

Figure 1 The process of P/Invoke

When one invokes an unmanaged function from managed code the following sequence of actions occurs:

First the Common Language Runtime

  • locates the DLL containing the function,

  • loads the DLL into memory,

  • locates the address of the function in memory and pushes its arguments onto the stack, marshaling data as required, using the standard marshaller or as we specify (it’s worth noting that locating and loading the DLL, and locating the address of the function in memory occur only on the first call to the function)

  • transfers control to the unmanaged function.

Also P/Invoke throws exceptions generated by the unmanaged function to the managed caller. In order to locate a function, one must specify at least the name of the function and name of the DLL that contains it. Each exported function will have a start address in the DLL and is called as the Entrypoint. (Note: It’s not that DLLMain!) To invoke a function you should tell the runtime the DLL name and the function name (or the ordinal number).To do so you use the DllImport attribute with the function prototype. To use this attribute you need to include the following statements to your code. This enables us to use the DllImport attribute available to us for use in our code.

[Visual Basic]
Imports System.Runtime.InteropServices

[C#]
using System.Runtime.InteropServices

Now comes the syntax that we may use for declaring such an unmanaged imported function as below. Consider the MesssageBox function that the user32.dll exports for our use. To introduce the MessageBox function in the User32.dll we declare a function (in C#) as

[DllImport(“user32.dll”)]
public static extern int MessageBox(int hWnd, String text, String caption, uint type);

{mospagebreak title=Two Versions}

The Microsoft Windows application programming interface (Win32 API) usually contains two versions of every function that handles characters and strings: a 1-byte character ANSI version and a 2-byte character Unicode version. When unspecified, the character set, represented by the CharSet field, defaults to ANSI. Some functions can have more than two versions. You may specify the exact version by providing additional attributes, as in the example below for the MoveFile API’s Unicode version of the function. You may lookup for more explanation on these attributes in the .NET online help.

[C#]
[DllImport(“KERNEL32.DLL”, EntryPoint=”MoveFileW”,  SetLastError=true,
CharSet=CharSet.Unicode, ExactSpelling=true,
CallingConvention=CallingConvention.StdCall)]
public static extern bool MoveFile(Stringstr src, String strdst);

A good practice is to group all the related functions in a class and let the class contain all these function prototypes.

Apart from these function prototypes you’ll also need to provide any Structures’, Unions’, and constants’ definitions because in the .NET FCL these are not available. (For example the POINT structure or the NMHDR structure, if you’re trying to process a Common Control notification in your .NET application.) In the case of our Managed Smart Card Library, we will not be using any callbacks, but if needed you may refer to implementing callbacks in the online help.

Next comes the point of marshalling. It’s quite important that the .NET runtime understands what we’re trying to pass to the unmanaged function, and what we expect back after its execution. We need to use the Reflection namespace for this purpose, so we may include in our code the following lines:

[Visual Basic]
Imports System.Reflection

[C#]
using  System.Reflection

Using this attribute we may specify how the data we pass or expect in return should be treated. You’ll need a bit of time to get used to the types you encounter while making calls to the native API. You may also use the table in the MSDN online help for the table that gives a mapping of the .NET types and the unmanaged types. If you use a third party DLL you must be cautious about these MarshalAs attributes, and use them where required. In most cases you’ll need them.

{mospagebreak title=The Managed Smart Card Sample}

The following code snippet will let you experiment with the Smart Card reader and the Smart Card directly from the managed code, and you’ll not need to create or use any COM components. But you must be aware of the Smart Card programming APIs with the platform SDK. For a quick start you may want to refer to my previous article of this series, Smart Cards in .NET. (https://www.aspfree.com/c/a/.NET/Smart-Cards-in-.NET/)

You may also download the demo code for this article here:

http://images.devshed.com/af/stories/Smart Cards in .NET Part 2/supportfile.zip

Feel free to modify this code in any way you like.

First we fire up the Visual Studio .NET IDE and create a new Windows application in C#. Declare the prototypes as below:

// WinSCard API’s to be imported
[DllImport(“WinScard.dll”)]
public static extern int SCardEstablishContext(uint dwScope,
int nNotUsed1,
int nNotUsed2,
ref int phContext);

[DllImport(“WinScard.dll”)]
public static extern int SCardReleaseContext(int phContext);

[DllImport(“WinScard.dll”)]
public static extern int SCardConnect(int hContext,
string cReaderName,
uint dwShareMode,
uint dwPrefProtocol,
ref int phCard,
ref int ActiveProtocol);

[DllImport(“WinScard.dll”)]
public static extern int SCardDisconnect(int hCard, int Disposition);

[DllImport(“WinScard.dll”)]
public static extern int SCardListReaderGroups(int hContext,
ref string cGroups,
ref int nStringSize);

[DllImport(“WinScard.dll”)]
public static extern int SCardListReaders(int hContext,
string cGroups,
ref string cReaderLists,
ref int nReaderCount);

[DllImport(“WinScard.dll”)]
public static extern int SCardFreeMemory(int hContext,
string cResourceToFree);

[DllImport(“WinScard.dll”)]
public static extern int SCardGetAttrib(int hContext,
uint dwAttrId,
ref byte[] bytRecvAttr,
ref int nRecLen); 

These declarations enable us to use these functions as we’d in our unmanaged C++ code.

{mospagebreak title=Our Interface}

Next we use these API’s to find all the readers attached to the system on which we run this application. The application presents an interface as below:

Smart Cards in .NET Part 2

Figure 2 GUI of the Demo application

The comments in the demo code are pretty descriptive and will explain the flow of the program. First we use the SCardEstablishContext API to acquire a context handle from the resource manager, and then call the SCardListReaderGroups to find all the reader groups on the system. We next find all the readers in the first group using the SCardListReaders API to find all the system readers. For each found reader a message is displayed and is added to the list box. I have a ACS30 USB reader connected and that is listed in the UI above.

You may play with this code, changing the code here and there just to see how the code behaves, and soon you’ll be able to make any calls that you want into the unmanaged DLL world.

{mospagebreak title=Points of Interest}

In this article we’ve learned a lot that could be used to use functions in native DLLs from the managed code. A few interesting points are:

  • This can be used in a number of ways, such as in the case of Windows hooks, where one needs to place the hook function in a Win32 DLL. That makes it difficult to implement hooks in a managed application, but this technique would allow us to do so without any problems.

  • The Default marshaller can interpret the data transferred during a Platform Invoke function call in a few/default ways. If we need the data to be interpreted differently, we may use the MarshalAs attribute to marshal that in the way we like. That’ll make a function behave the way we want it to.

  • Please note that this does not always work with all types, and the runtimes notify us at runtime by throwing an exception. Do use exception handling to ensure that your program handles the error conditions gracefully.

Summary

After this article we are a step near to developing our own Managed wrapper on the full WinSCard API that we can use to develop Smart Card enabled applications in .NET. In the next and concluding part of this series of article I shall show you how to do just that with the help of an extensive sample and full library code.

18 thoughts on “Smart Cards in .NET, Part 2

  1. Hi I’m Digvijay . the author of this article.Please feel free to ask any questions that you may have on this discussion list or by mailing me.

    -Digvijay

  2. Hi. Your code won’t work if you have more readers connected to one pc. I have multiple readers connected to my pc and discovered a problem in the code.

    The problem has to do with the importing of the ListReaders Method.

    [DllImport(“WinScard.dll”)]
    public static extern int SCardListReaders(int hContext,
    string cGroups,
    ref string cReaderLists,
    ref int nReaderCount); < - Not actual count of readers but length of string of readers.

    This method returns a string array with all readers. After each reader a ‘\0’ charachter is found. The string object in C# will not copy anything found after the \0 thus always finding only 1 reader.

    To fix this do the following:

    [DllImport(“winscard.dll”)]
    public static extern int SCardListReaders(IntPtr hContext,
    string mszGroups,
    byte[] mszReaders, < - Here is the difference.
    out uint pcchReaders);

    You have to call this function two times. The first time to get the actual length of the string of readers (pcchReaders). Then you can create a byte[] with the correct size. -> byte[pcchReaders].

    Then call the method again to actually fill the byte[] with the readers.

    Once this is done you have to parse the byte[] to split up the readers.

    Hope this helps some people!!

  3. hi,
    your article was excellent,but u did not provide any code for accessing data from the smart card.. i am very new to smart card accessing..
    can you please send me the code in .net for accessing data from smart card ?

    thanks very much in advance…

    regards,
    thiru.s

  4. hi i read your article, its very nice.. but there are no code to connect and read the data from the smart card in .net

    could you please send the code for connecting and reading data from smart card in c# or vb.net in .net ?

    thanks in advance.

    Regards,
    Thiru.S

  5. Hi Thiru,

    Sorry but right now i am away from work in Sweden doing my Masters in Security.
    Have no code for this article with me. You might consider reading the third part which has some code in c# for download.

    please let me know if you have any questions.

    Regards,

    Digvijay

  6. hi

    thanks alot for this lesson.

    i have some questions please :

    **** i am student in the last year of CS and i have agraduate project in SMART CARD in C# ,the idea of our projects is (attendance & departing system) for employees without control the opening or closing the door just recieve the time and date from smart card reader and i want to ask u which is better for me using :

    1- P/Invoke and access the WinSCard.dll raw API

    ,OR

    2-use the System.Runtime.InteropServices namespace which provides a collection of classes useful for accessing COM objects, and native APIs from .NET. (recommended for me because it is easear)

    and where i can found the source code for this article ……?

    can u write the code that provide access pc to the sc …..please very important and

    thaaaanks ….

  7. hye.. i already read your article.. it great. its give me an overviw abiut smart card application..but can you provide a code to acess the data.. im new in .net application..

  8. to which file should i paste the following code

    // WinSCard API’s to be imported
    [DllImport(“WinScard.dll”)]
    public static extern int SCardEstablishContext(uint dwScope,
    int nNotUsed1,
    int nNotUsed2,
    ref int phContext);

    [DllImport(“WinScard.dll”)]
    public static extern int SCardReleaseContext(int phContext);

    [DllImport(“WinScard.dll”)]
    public static extern int SCardConnect(int hContext,
    string cReaderName,

    ………

  9. you do the attendance system using smart card ?? so have yuo sucessfully done it?? can you tech me how to do it??

  10. hi digvijay,
    sir i want to know a few details about smart cards…
    i am trying to add this dll “WinScard.dll” in to my project that gives me an error ….
    Now there is a namespace in .net framework that in turn calls all these API’s when used, but when i try to using that namespace that dll or namespace doesn’t exist……..”Microsoft.PointOfService.dll”

    can u help me with these 2 issues …..please

  11. Hi,

    Yes i did this about two years ago but right now i am quite busy with my thesis work as a Masters Student so can not write some code for you.

    If i find some resources i shall surely share then with you.

    /Digvijay

  12. Hi DigVijay,

    I read your article, it nice, but i am new to MFC, I have to digitally sign a document(any file doc,pdf,xls,ppt etc). Before that I have to read the data from the PKI Card that has a certificate and user Information.
    Could you help me from where to start for this, you can mail me at rajkumarrathor@gmail.com.

    Thanks in Advance.

    Raj

  13. Hi Dig,
    You can implemented SCardConnect(), a sample explain.
    I can not implement SCardConnect() function.
    Thanks.

[gp-comments width="770" linklove="off" ]