<img src=“https://travis-ci.org/larskanis/pkcs11.png?branch=master” alt=“Build Status” />

• Homepage: github.com/larskanis/pkcs11

• API documentation: rubydoc.info/gems/pkcs11/frames

This module allows Ruby programs to interface with “RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki)”. PKCS #11 is the de-facto standard to access cryptographic devices. You must have a PKCS #11 v2.20 implementation library installed in order to use this module. Tested implementations of PKCS#11 librarys include:

• OpenSC supported Smart Cards

• Safenet - Protect Server HSMs

• Mozilla_Soft_Token which comes with every firefox installation

This module works on the Unix like operating systems and win32.

gem install pkcs11

This installs the PKCS#11 extension either by compiling (Unix) or by using the precompiled gem for Win32.

Cryptoki has a reputation to be complicated to implement and use. While this seems to be true for C, it shouldn’t for Ruby.

• {PKCS11.open} opens a PKCS#11 Unix *.so file or Windows-DLL with a suitable PKCS #11 implementation and returns a {PKCS11::Library}.

• {PKCS11::Library#slots} returns a list of {PKCS11::Slot} for all slots accessable by the library.

• {PKCS11::Slot#open} opens a {PKCS11::Session} which is used for object handling and cryptographic operations.

• {PKCS11::Object} represents a key, data or certificate object.

• all constants defined in PKCS#11 v2.20 are available in the module {PKCS11} and contain the associated Integer value (CKA_KEY_TYPE, CKK_AES, CKM_SHA_1 etc.)

• also all PKCS#11 v2.20 structs are available in the module {PKCS11} as proper ruby classes ({PKCS11::CK_VERSION}, {PKCS11::CK_OTP_PARAMS} etc.)

require "rubygems"
require "pkcs11"
include PKCS11

pkcs11 = PKCS11.open("/path/to/pkcs11.so")
p pkcs11.info  # => #<PKCS11::CK_INFO cryptokiVersion=...>
pkcs11.active_slots.first.open do |session|
  session.login(:USER, "1234")
  secret_key = session.generate_key(:DES2_KEY_GEN,
    :ENCRYPT=>true, :DECRYPT=>true, :SENSITIVE=>true, :TOKEN=>true, :LABEL=>'my key')
  cryptogram = session.encrypt( {:DES3_CBC_PAD=>"\0"*8}, secret_key, "some plaintext")
  session.logout
end

This opens a {PKCS11::Library PKCS#11 library} and prints it’s {PKCS11::CK_INFO information block}. Then a {PKCS11::Session} to the first {PKCS11::Library#active_slots active slot} of the device is opened and a {PKCS11::Session#login login} is done on the user account. Now, a 112 bit DES3 {PKCS11::Object key object} is generated and some plaintext is {PKCS11::Session#encrypt encrypted} with it. A 8-byte zero IV is used. In many cases method parameters can be Integer (like PKCS11::CKA_LABEL) or, as in the sample, Symbol (:LABEL) which is internally converted.

Many more usage examples can be found in the unit tests of the test directory of the project or gem.

Detail information for the API specification is provided by RSA Security Inc. Please refer the URL: www.rsa.com/rsalabs/node.asp?id=2133. Browsable HTML can be found at www.cryptsoft.com/pkcs11doc.

Some vendors extend their libraries beyond the standard, in it’s own way. This can be used by vendor specific packages:

• Safenet ProtectServer: {file:pkcs11_protect_server/README_PROTECT_SERVER.rdoc}

The pkcs11 binding fully supports native, background Ruby threads. This of course only applies to Rubinius and Ruby 1.9.x or higher since earlier versions of Ruby do not support native threads.

According to the standard, calling the Cryptoki library from multiple threads simultaneously, requires to open it with flag PKCS11::CKF_OS_LOCKING_OK. Application-supplied synchronization primitives (CreateMutex, DestroyMutex, LockMutex, UnlockMutex) are not supported.

Using rake-compiler a cross compiled pkcs11-gem can be build on a linux host for the win32 platform. There are no runtime dependencies to any but the standard Windows DLLs.

Install mingw32. On a debian based system this should work:

apt-get install mingw32

On MacOS X, if you have MacPorts installed:

port install i386-mingw32-gcc

Install the rake-compiler:

gem install rake-compiler

Download and cross compile ruby for win32:

rake-compiler cross-ruby VERSION=1.8.7-p352
rake-compiler cross-ruby VERSION=1.9.2-p290

Download and cross compile pkcs11 for win32 (MRI 1.8+1.9 fat gem):

rake cross native gem RUBY_CC_VERSION=1.8.7:1.9.2

If everything works, there should be pkcs11-VERSION-x86-mingw32.gem in the pkg directory.

• encoding support for Ruby 1.9

• support for proprietary extensions of different vendors (done for Safenet-ProtectServer)

• PKCS#11 v2.3

Any operation that is possible with PKCS#11 in C, should be likewise possible in Ruby. Otherwise it is considered as a bug in the binding.

STATE   FUNCTION               NOTE
------  ---------------------  ----------------------------------------
DONE    C_Initialize
DONE    C_Finalize
DONE    C_GetInfo
DONE    C_GetFunctionList
DONE    C_GetSlotList
DONE    C_GetSlotInfo
DONE    C_GetTokenInfo
DONE    C_GetMechanismList
DONE    C_GetMechanismInfo
DONE    C_InitToken
DONE    C_InitPIN
DONE    C_SetPIN
DONE    C_OpenSession
DONE    C_CloseSession
DONE    C_CloseAllSessions
DONE    C_GetSessionInfo
DONE    C_GetOperationState
DONE    C_SetOperationState
DONE    C_Login
DONE    C_Logout
DONE    C_CreateObject
DONE    C_CopyObject
DONE    C_DestroyObject
DONE    C_GetObjectSize
DONE    C_GetAttributeValue
DONE    C_SetAttributeValue
DONE    C_FindObjectsInit
DONE    C_FindObjects
DONE    C_FindObjectsFinal
DONE    C_EncryptInit
DONE    C_Encrypt
DONE    C_EncryptUpdate
DONE    C_EncryptFinal
DONE    C_DecryptInit
DONE    C_Decrypt
DONE    C_DecryptUpdate
DONE    C_DecryptFinal
DONE    C_DigestInit
DONE    C_Digest
DONE    C_DigestUpdate
DONE    C_DigestKey
DONE    C_DigestFinal
DONE    C_SignInit
DONE    C_Sign
DONE    C_SignUpdate
DONE    C_SignFinal
DONE    C_SignRecoverInit
DONE    C_SignRecover
DONE    C_VerifyInit
DONE    C_Verify
DONE    C_VerifyUpdate
DONE    C_VerifyFinal
DONE    C_VerifyRecoverInit
DONE    C_VerifyRecover
DONE    C_DigestEncryptUpdate
DONE    C_DecryptDigestUpdate
DONE    C_SignEncryptUpdate
DONE    C_DecryptVerifyUpdate
DONE    C_GenerateKey
DONE    C_GenerateKeyPair
DONE    C_WrapKey
DONE    C_UnwrapKey
DONE    C_DeriveKey
DONE    C_SeedRandom
DONE    C_GenerateRandom
N/A     C_GetFunctionStatus    legacy function
N/A     C_CancelFunction       legacy function
DONE    C_WaitForSlotEvent

• Ryosuke Kutsuna <ryosuke@deer-n-horse.jp>

• GOTOU Yuuzou <gotoyuzo@notwork.org>

• Lars Kanis <kanis@comcard.de>

See MIT-LICENSE included in the package.