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.
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.
Figure 1The 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.
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);
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.
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.
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. (http://www.aspfree.com/c/a/.NET/Smart-Cards-in-.NET/)
You may also download the demo code for this article here:
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.
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:
Figure 2GUI 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.
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.
Smart Cards in .NET
