In part II, we learned how to use platform invoke in .NET to access the raw APIs exported by the WinSCard.dll and use them in our own applications. That was an introduction explaining how we are going to going to access the native Smart Card APIs. In this article, we will learn how to write the library itself, by writing a managed wrapper for using smart cards in .NET.
In the last article, we learned how to use platform invoke in .NET to access the raw APIs exported by the WinSCard.dll and use them in our own applications. The basic example code for finding readers attached to system was also provided. That was just an introduction explaining how we are going to access the native Smart Card APIs, and now we shall write the library itself. If you have not read the last article, I’d recommend that you to skim though it once, just to understand the code in this article.
The code for this library is written in C#, so I’d expect you to be familiar with the C# language. This is not compulsory, however, because equivalent code can be written in VB .NET--or any .NET compliant language for that matter. Because the library generated with our code is a Managed one, we can use it from any .NET compliant language. As for this library, the demo you’ll find is written in VB .NET.
So without any further ado let’s get started with our library.
Designing our classes
To begin with the design of our classes for this library, we can look at the way the API’s in the WinSCard.dll are organized. They’re organized in the following categories:
Smart Card Database Query Functions
Smart Card Database Management Functions
Resource Manager Context Functions
Smart Card Tracking Functions
Smart Card and Reader Access Functions
Direct Card Access Functions
The database query functions query the smart card database, and they can provide a list of smart cards that are supplied by a specific user, the interfaces, and the primary service provider of a specific smart card. These functions can be used to query the complete smart card database, or a part of it, by setting the resource manager context appropriately. The resource manager context is set by calling one of the Context functions prior to invoking a query function. The success of the called function also depends on the state of the Smart Card Service and the Security context of the calling application. Similarly, the database management functions manage the smart card database and update the database by using a specified resource manager context.
The context functions, on other hand, establish and release the resource manager context, which is used by the database query and database management functions. Tracking functions allow for tracking smart cards within readers attached to the system. Most important are the reader access functions that connect to and communicate with a specific smart card, and manage the data structures for communicating and transferring data to/from the Smart Card. All protocol related details are also set and observed here. Since this is not a perfect world, one sometimes gets cards that are not ISO 7816 compliant, and to access such cards Direct Card access functions come to the rescue.
Working along the following lines, we may have two classes: one for resource manager, and another for reader functions, so that they encapsulate the Resource Manager and the Smart Card reader itself. A few helper classes that let you deal with the data exchanged with the card and the commands that you pass to the card can also be added, as I’ve done in our library.
As with any other component, library errors and exceptions are something that we can’t ignore, so I’ve also included a SCardException class, which itself derives from ApplicationException class and provides encapsulation on the response code from the card. Added to that, you can raise an exception based on a Win32 error code that you usually get from the native WinSCard API. Also, an internal sealed class WinSCard provides the primitives for P/Invoking the native APIs, and you may have a look at it in the attached code for this article.
So at this point our classes look like this:
Figure 1 Classes for our Library
The class SCResMgr contains the code to manage Contexts with the Smart Card Resource Manager and lets us use it with an instance of SCReader. Indeed, you can’t create a SCReader without a SCResMgr!
Let’s have a look at the members of the SCResMgr:
public void Cancel()
Is a member Equivalent to native SCardCancel() and the code looks something like the code below:
// Tracking Functions public void Cancel() { if (this.m_hContext == IntPtr.Zero) { throw new InvalidOperationException(); } uint nErrCode = WinSCard.SCardCancel(this.m_hContext); if (nErrCode != 0) { SCardException.RaiseWin32ResponseCode(nErrCode); } }
public bool EstablishContext(SCardContextScope nScope)
Is equivalent to SCardEstablishContext and uses encapsulated Context handle. Note how the Context Scope constants in the platform SDK have been grouped in an enum to facilitate their use.
public bool GetStatusChange(int nTimeout, SCStateInfo[] vaSCStates)
Is similar to the SCardGetStatusChange API and this contains three overloads to make its use easier as compared to the native API.
These three examples above will be able to explain to you the style adopted for the library. You will find more details as you get to use the library. For a quick look refer to figure 2, which shows all the members of the SCResMgr library. For a more detailed view, look at the source code listing for the SCResMgr API later in the article.
Figure 2SCResMgr Class View
Next you may see the Class created for SCReader that encapsulates a Smartcard Reader in figure 3.
Figure 3 The SCReaderClassView
Finally you can see all the classes and Enumerations in the figure below. This code, being a part of a commercial product, can’t be released publicly, but a free compiled version is certainly a strong candidate for release with this article.
You will find the compiled Library and the demo with source code in the zip file for this article. Tracing through the code, you’ll realize how easy it is to use this library. As I’ve not provided any help manual for the compiled library, you’ll have to rely on the intellisence of the VS.NET IDE for prototypes.
As a reference I’ve included the source code for the SCResMgr Class and the WinSCard.cs file that contains the DllImports to the native functions. They’ll help you understand how the library is implemented.
The WinSCard.cs file contents are as below:
using System; using System.Text; using System.Runtime.InteropServices;
namespace SCLib { internal sealed class WinSCard { // Methods public WinSCard() { }
The WinSCard is a sealed class, so you won’t be able to derive from it, but you may refer to it occasionally if you wish to invoke a function directly from your own P/Invoke code. And below, you’ll find code for the SCResMgr.cs that encapsulates the Smart Card resource manager.
using System; using System.Collections; using System.Windows.Forms; using System.Runtime.InteropServices;
namespace SCLib { public sealed class SCResMgr : IDisposable { // Methods public SCResMgr() { this.m_fDisposed = false; this.m_hContext = IntPtr.Zero; }
private int _SplitMultiString(string msz, IList aList) { int nTemp; int nCount = 0;
// For each string for (int nIter = 0; msz[nIter] != '\0'; nIter = nTemp + 1) { nTemp = nIter;
// While not end of String while (msz[nTemp] != '\0') { nTemp++; } aList.Add(msz.Substring(nIter, nTemp - nIter)); nCount++; }
// Return Count return nCount; }
~SCResMgr() { this._Dispose(false); }
public void Dispose() { this._Dispose(true); GC.SuppressFinalize(this); }
// Context Functions public bool EstablishContext(SCardContextScope nScope) { if (this.m_fDisposed) { throw new ObjectDisposedException(base.GetType().FullName); } if (this.m_hContext != IntPtr.Zero) { throw new InvalidOperationException(); } uint nErrCode = WinSCard.SCardEstablishContext((uint) nScope, IntPtr.Zero, IntPtr.Zero, out this.m_hContext);
// If Service not running if (nErrCode == 0x8010001d) { MessageBox.Show("The ensure that SCardSvr Service is running. PC/SC routines won't be available."); return false; }
// else there is some other problem if (nErrCode != 0) { MessageBox.Show(string.Format("SCardEstablishContext failed: 0x{0:X8}", nErrCode)); SCardException.RaiseWin32ResponseCode(nErrCode); } return true; }
public void ReleaseContext() { // Sanity Check if (this.m_fDisposed) { throw new ObjectDisposedException(base.GetType().FullName); }
// Check Context if (this.m_hContext == IntPtr.Zero) { throw new InvalidOperationException(); } uint nErrCode = WinSCard.SCardReleaseContext(this.m_hContext);
// Set Zero this.m_hContext = IntPtr.Zero;
// Was there an error if (nErrCode != 0) { SCardException.RaiseWin32ResponseCode(nErrCode); } }
public bool IsValidContext() { // Sanity Check if (this.m_fDisposed) { throw new ObjectDisposedException(base.GetType().FullName); }
// Verify Context exists if (this.m_hContext == IntPtr.Zero) { throw new InvalidOperationException(); }
// If Timeout or SCardCancel happened just bail out if ((nErrCode == 0x8010000a) || (nErrCode == 0x80100002)) { return false; } // If we reach here there is a problem SCardException.RaiseWin32ResponseCode(nErrCode); throw new InvalidProgramException(); }
// Database Functions public int ListReaderGroups(IList aReaderGroupsList) { // Sanity Check if (this.m_fDisposed) { throw new ObjectDisposedException(base.GetType().FullName); } // Sanity Check if (this.m_hContext == IntPtr.Zero) { throw new InvalidOperationException(); }
public int ListReaders(IList aReadersList) { return this.ListReaders((string[]) null, aReadersList); }
public int ListReaders(string sGroup, IList aReadersList) { // Sanity Check if ((sGroup == null) || (sGroup.Length == 0)) { throw new ArgumentNullException(); } string[] textArray = new string[1] { sGroup } ; return this.ListReaders(textArray, aReadersList); }
public int ListReaders(string[] vsGroups, IList aReadersList) { // Sanity Check if (this.m_fDisposed) { throw new ObjectDisposedException(base.GetType().FullName); } if (this.m_hContext == IntPtr.Zero) { throw new InvalidOperationException(); }
int nReaders = 0; string text = null; if ((vsGroups != null) && (vsGroups.Length > 0)) { string[] textArray = vsGroups; for (int nIter = 0; nIter < textArray.Length; nIter++) { string strTemp = textArray[nIter]; text = text + strTemp; text = text + '\0'; } text = text + '\0'; } IntPtr ptrMem = IntPtr.Zero;
The CardCommand Class will allow you to create and use the ISO-7816 compliant APDUs and the SCUtil helper class can help you convert strings to byte arrays for Transmitting and converting the Smart Card response from a byte array to String for display in the UI or console. Other enums often will be used as function parameters and are self-explanatory.
Another feature is the SelectSmartCard Dialog, which lets the user select a reader from the system readers through UI. To use it, just call this static method from the SCReaser class. Also, take a look at the types you’ll be dealing with in the listing for file (can be found in the source code) Types.cs:
using System; using System.Runtime.InteropServices;
[StructLayout(LayoutKind.Sequential)] public struct SCStateInfo { public string sReaderName; public SCStates nCurrentState; public SCStates nEventState; public byte[] vbATR; }
You can download the compiled library and source code for the demo using the library here. It contains the library, as a DLL, that we designed above, as well as the sample application that we can use to peek at how the library works. The library is written using VS .NET 2003 architect, and the library code and the demo application code are in C# and VB .NET respectively.
The compiled library and the demo with source code come with no warranty of any kind. You’re free to use it in any way, but I’d appreciate it if you mail me if you find any bugs while using it, and use it in a Commercial, Freeware or Shareware application or product.
Points of Interest
The design of this library is not very fine, but it is more than enough for writing a full-fledged Smart Card application. You have unrestricted rights to use and distribute the compiled library as you wish, but I’d appreciate an email about the same, or maybe some code snippets. Feel free to contact me if you have any feature requests.
The underlying WinSCard.dll itself complies with PC/SC v1.0, and the draft version of 2.0 is out on http://www.pcscworkgroup.com, so you may want to have a look at the new specification before you get the new implementations, just to have an idea of the shortcomings in the current implementation.
Summary
In this article we learned about writing a pure managed wrapper on the WinSCard API, and used it in a VB .NET application to communicate with a Smart Card. This can be a good starting point for writing a Smart Cards commercial library in .NET to many of you. I hope that it will get you started with writing applications that access and use smart cards in .NET. In case you have any doubts or confusion about the code, you may always write to me and I shall surely write back to you with an answer. Any comments and suggestions are also welcome.
Smart Cards in .NET, Part 2
