Documentation

Introduction

NCryptoki is a library for .NET framework, Silverlight, JavaScript and Java SE that implements the PKCS#11 specifications and supplies an API for C#, VB.NET, Visual Basic 6, Java, Delphi and other COM interop languages for integrating a PKCS#11 compliant token in any application.
NCryptoki maps the cryptoki's functions defined in PKCS#11 specification in a set of high level classes usable in C#, VB.NET or Java and propose a programming paradigm that allows to integrate your PKCS#11 compliant token in your applications easily with a few lines of code.
NCryptoki supplies also a COM interface that allows to use the supplied classes in any language that supports COM interop like Visual Basic 6, Delphi etc.
The main features are:

Compliant with PKCS#11 2.20 specifications
Compliant with any PKCS#11 token
32 or 64 bit platform
.NET Framework 3.5 or later
Java 6 or later

PKCS#11

PKCS#11 (Public Key Cryptography Standards No. 11) specifications, developed by RSA Data Security labs, defines an high-level, platform-independent API to cryptographic devices (such as smart cards, USB Tokens, HSMs, etc.), that hides the low level operational logic of a cryptographic devices, presenting to the applications a unified abstraction layer for a generic cryptographic token with an higher level set of functions.
The high flexibility and the simple logic of such a model made the PKCS#11 specifications a de-facto standard widely used by applications interacting with smart cards. PKCS#11 is largely adopted to access smart cards, cryptographic tokens and HSMs. Most commercial Certification Authority software uses PKCS#11 to access the CA signing key or to enroll user certificates as well as cross-platform software that needs to use smart cards uses PKCS#11, such as Mozilla Firefox and OpenSSL (using an extension).

Because the API is defined in C language, the PKCS#11 module is implemented in C as native library (a Dinamically Linked Library (.dll) in Windows OS or as Shared Object (.so) on Linux and MacOS) that exports the functions of the API. This means that if your application is in C/C++ you can easily import the API functions in your code, But what if your application is in C# or VB.NET? Or what if you application is in Visual Basic 6 or Delphi? NCryptoki addresses this stuffs and allows to call PKCS#11 API in your .NET applications.

Architecture

A typical Cryptoki-based system architecture is depicted in Figure 2.
The cryptographic device (aka token) is connected to the system via a slot. Typically, a slot corresponds to a smart card reader or a specific card terminal. However, because Cryptoki offers a purely logical view of the system it could happens that different slots point to the same physical reader device or, viceversa, a single slot could have more than one device.

The logical structure of a token

A specific Cryptoki implementation maps the token’s physical structure, typically composed by memory zones in which data, cryptographic keys and their digital certificates are stored, into a logical structure that adheres to the hierarchical model shown in Figure 3.
The specifications define three main object classes:

Data objects host generic data which semantics is defined by the application who created them;
Certificate objects store digital certificates;
Key objects contain a public, private or secret cryptographic key.

Cryptoki’s objects are classified depending on their visibility in public objects (i.e. accessible by all applications), and private objects (visible only after granting access permissions typically performed via PIN-verification as described later), and on their persistency in: token objects which persist when the token is plugged-out from the slot and in session objects which don’t persist. For each class of objects the specifications define a set of attributes (as described later) characterizing all instances of the class, which, are inherited by derived classes, similarly to an object-oriented model (for example, the Private Key class inherits all attributes from the Key class etc.)

The PKCS#11 API

PKCS#11 specifications define an API named Cryptoki (CRYPtographic TOKen Interface) that implements an API to an abstract model of a cryptographic device, such as a microprocessor-based smart card, a USB cryptographic token or an HSM. The API follows a simple object-based approach, addressing the goals of technology independence (any kind of device) and resource sharing (multiple applications accessing multiple devices), presenting to applications a common, logical view of the device called a cryptographic token. The API defines the most commonly used cryptographic object types (RSA keys, X.509 Certificates, DES/Triple DES keys, etc.) and all the functions needed to use, create/generate, modify and delete those objects:
The programming language used to define the functions and data types is ANSI C. Along with specifications, RSA Data Security published three C header files (pkcs11.h, pkcs11t.h and pkcs11f.h, available at this page: http://www.rsa.com/rsalabs/node.asp?id=2133) that define function prototypes, Cryptoki-specific data types and a set of macros to manage objects classes and their attributes.

Using the Cryptoki API in a .NET or Java application

As we said above, the API is defined in C language and the PKCS#11 modules are implemented in C as native unmanaged libraries. In order to use it in a .NET or Java application we have no chance to avoid from using platform invoke services (P-Invoke), supplied by the .NET framework, or JNI, to import the unmanaged functions of the native API in our C#, VB.NET or Java managed code. But importing such functions from an unmanaged dll, expecially from a highly complex PKCS#11 dll, requires very advanced skills in C/C++ and .NET or Java and compels a lot of tedious work to write the declaration of the prototypes related to the functions using the P-Invoke/JNI rules and to deal with the marshalling of custom parameters.
NCryptoki library allows to avoid from dealing with P-Invoke or JNI declarations and unmanaged code saving a lot of tedious work.

NCryptoki

NCryptoki is a library for .NET framework that implements the PKCS#11 specifications and supplies an API for C#, VB.NET, Visual Basic 6, Delphi and other COM interop languages for integrating a PKCS#11 compliant token in any application.
NCryptoki maps the cryptoki's functions defined in PKCS#11 specification in a set of high level classes usable in C#, VB.NET and propose a programming paradigm that allows to integrate your PKCS#11 compliant token in your applications easily with a few lines of code.
NCryptoki supplies also a COM interface that allows to use the supplied classes in any language that supports COM interop like Visual Basic 6, Delphi etc.
The programming paradigm is very similar to the one described in C programming language in PKCS#11 specifications: the PKCS#11 C functions are mapped into a set of .NET classes that follows the same classification described above.
Figure 1 at right shows the class hierarchy of NCryptoki.
Cryptokiis the main class that allows to use the library, the classes Slot and Token enclose the slot-handling and token-handling functions, while the class CryptokiObject encapsulates the object-handling functions as well as the definitions related to objects’ classes and their attributes. The class Session includes the OpenSession and CloseSession functions, the functions related to login and logout, the search functions to search for PKCS#11 objects and, finally, the cryptographic and hashing functions and the other functions defined in the PKCS#11 specifications.

JCryptoki

JCryptoki is a package for Java SE that implements the PKCS#11 specifications and supplies a Java API to any PKCS#11 compliant token/HSM. JCryptoki maps the cryptoki's functions defined in PKCS#11 specification in a set of high level classes usable in Java and in JavaScript and proposes a programming paradigm that allows to integrate your PKCS#11 compliant token in your Java applications and/or in your web pages easily with a few lines of code.
The programming paradigm is very similar to the one described in C programming language in PKCS#11 specifications: the PKCS#11 C functions are mapped into a set of Java classes that follows the same classification described above.
Cryptokiis the main class that allows to use the library, the classes Slot and Token enclose the slot-handling and token-handling functions, while the class CryptokiObject encapsulates the object-handling functions as well as the definitions related to objects’ classes and their attributes. The class Session includes the OpenSession and CloseSession functions, the functions related to login and logout, the search functions to search for PKCS#11 objects and, finally, the cryptographic and hashing functions and the other functions defined in the PKCS#11 specifications.

Documentation

The documentation is available here:

Online HTML:

Wiki: http://wiki.ncryptoki.com/

White Paper (PDF): How to use NCryptoki