<commit_before>= PKCS #11/Ruby Interface

* Homepage: http://github.com/larskanis/pkcs11
* API documentation: http://pkcs11.rubyforge.org/pkcs11/

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[http://www.opensc-project.org] supported Smart Cards
* Safenet[http://www.safenet-inc.com] - Protect Server HSMs
* Mozilla_Soft_Token[https://developer.mozilla.org/en/PKCS11] which comes with every firefox installation

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

== Installation

  gem install pkcs11

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

== Usage
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 structs are available in the module {PKCS11} as proper ruby classes
  ({PKCS11::CK_VERSION}, {PKCS11::CK_OTP_PARAMS} etc.)

=== Example
  require "rubygems"
  require "pkcs11"
  include PKCS11

  pkcs11 = PKCS11.open("/path/to/pkcs11.so")
  p pkcs11.info
  session = pkcs11.active_slots.first.open
  session.login(:USER, "<PASSWORD>")
  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
  session.close

This opens a PKCS#11 library and prints it's information block.
Then a {PKCS11::Session} to the first active slot of the device is opened and
a login is done on the user account. Now, a 112 bit DES3 key is generated and
some plaintext is encrypted with it. A 8-byte zero IV is used. In many cases method parameters
can be Integer (like 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 <tt>test</tt>
directory of the project or gem.

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


== Cross compiling for mswin32

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:
<commit_msg>add a README section about multithreading<commit_after>= PKCS #11/Ruby Interface

* Homepage: http://github.com/larskanis/pkcs11
* API documentation: http://pkcs11.rubyforge.org/pkcs11/

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[http://www.opensc-project.org] supported Smart Cards
* Safenet[http://www.safenet-inc.com] - Protect Server HSMs
* Mozilla_Soft_Token[https://developer.mozilla.org/en/PKCS11] which comes with every firefox installation

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

== Installation

  gem install pkcs11

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

== Usage
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 structs are available in the module {PKCS11} as proper ruby classes
  ({PKCS11::CK_VERSION}, {PKCS11::CK_OTP_PARAMS} etc.)

=== Example
  require "rubygems"
  require "pkcs11"
  include PKCS11

  pkcs11 = PKCS11.open("/path/to/pkcs11.so")
  p pkcs11.info
  session = pkcs11.active_slots.first.open
  session.login(:USER, "<PASSWORD>4")
  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
  session.close

This opens a PKCS#11 library and prints it's information block.
Then a {PKCS11::Session} to the first active slot of the device is opened and
a login is done on the user account. Now, a 112 bit DES3 key is generated and
some plaintext is 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 <tt>test</tt>
directory of the project or gem.

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


=== Threading

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.

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.


== Cross compiling for mswin32

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:

{'fraction_non_alphanumeric': 0.08184107442641299, 'fraction_numerical': 0.030358142137660884, 'mean_word_length': 4.669310071371927, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 21, 'https://': 2, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3158702', 'n_tokens_mistral': 2378, 'n_tokens_neox': 2166, 'n_words': 908}