class PKCS11::Session

Cryptoki requires that an application open one or more sessions with a token to gain access to the token's objects and functions. A session provides a logical connection between the application and the token. A session can be a read/write (R/W) session or a read-only (R/O) session (default).

Public Instance Methods

C_CloseSession() click to toggle source

Closes the session between an application and a token. @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 59
def C_CloseSession()
  @pk.C_CloseSession(@sess)
  self
end
Also aliased as: close
C_CreateObject(template={}) click to toggle source

Creates a new Object based on given template.

If {Session#C_CreateObject} is used to create a key object, the key object will have its CKA_LOCAL attribute set to false. If that key object is a secret or private key then the new key will have the CKA_ALWAYS_SENSITIVE attribute set to false, and the CKA_NEVER_EXTRACTABLE attribute set to false.

Only session objects can be created during a read-only session. Only public objects can be created unless the normal user is logged in.

@param [Hash] template Attributes of the object to create. @return [PKCS11::Object] the newly created object @example Creating a 112 bit DES key from plaintext

secret_key = session.create_object(
  :CLASS=>PKCS11::CKO_SECRET_KEY, :KEY_TYPE=>PKCS11::CKK_DES2,
  :ENCRYPT=>true, :WRAP=>true, :DECRYPT=>true, :UNWRAP=>true,
  :VALUE=>'0123456789abcdef', :LABEL=>'test_secret_key')
# File lib/pkcs11/session.rb, line 152
def C_CreateObject(template={})
  handle = @pk.C_CreateObject(@sess, to_attributes(template))
  Object.new @pk, @sess, handle
end
Also aliased as: create_object
C_Decrypt(data, out_size=nil) click to toggle source

Decrypts encrypted data in a single part.

See {Session#decrypt} for convenience. @param [Integer, nil] out_size The buffer size for output data provided to the

library. If nil, size is determined automatically.

@return [String]

# File lib/pkcs11/session.rb, line 334
def C_Decrypt(data, out_size=nil)
  @pk.C_Decrypt(@sess, data, out_size)
end
C_DecryptDigestUpdate(data, out_size=nil) click to toggle source

Continues a multiple-part combined decryption and digest operation, processing another data part.

Decryption and digesting operations must both be active (they must have been initialized with {Session#C_DecryptInit} and {Session#C_DigestInit}, respectively). This function may be called any number of times in succession, and may be interspersed with {Session#C_DecryptUpdate}, {Session#C_DigestUpdate}, and {Session#C_DigestKey} calls.

# File lib/pkcs11/session.rb, line 618
def C_DecryptDigestUpdate(data, out_size=nil)
  @pk.C_DecryptDigestUpdate(@sess, data, out_size)
end
C_DecryptFinal(out_size=nil) click to toggle source

Finishes a multiple-part decryption operation.

See {Session#decrypt} for convenience. @param [Integer, nil] out_size The buffer size for output data provided to the

library. If nil, size is determined automatically.

@return [String]

# File lib/pkcs11/session.rb, line 353
def C_DecryptFinal(out_size=nil)
  @pk.C_DecryptFinal(@sess, out_size)
end
C_DecryptInit(mechanism, key) click to toggle source

Initializes a decryption operation.

See {Session#decrypt} for convenience and {Session#C_EncryptInit} for description.

# File lib/pkcs11/session.rb, line 325
def C_DecryptInit(mechanism, key)
  @pk.C_DecryptInit(@sess, to_mechanism(mechanism), key)
end
C_DecryptUpdate(data, out_size=nil) click to toggle source

Continues a multiple-part decryption operation, processing another encrypted data part.

See {Session#decrypt} for convenience. @param [Integer, nil] out_size The buffer size for output data provided to the

library. If nil, size is determined automatically.

@return [String]

# File lib/pkcs11/session.rb, line 344
def C_DecryptUpdate(data, out_size=nil)
  @pk.C_DecryptUpdate(@sess, data, out_size)
end
C_DecryptVerifyUpdate(data, out_size=nil) click to toggle source

Continues a multiple-part combined decryption and verification operation, processing another data part.

Decryption and signature operations must both be active (they must have been initialized with {Session#C_DecryptInit} and {Session#C_VerifyInit}, respectively). This function may be called any number of times in succession, and may be interspersed with {Session#C_DecryptUpdate} and {Session#C_VerifyUpdate} calls.

# File lib/pkcs11/session.rb, line 640
def C_DecryptVerifyUpdate(data, out_size=nil)
  @pk.C_DecryptVerifyUpdate(@sess, data, out_size)
end
C_DeriveKey(mechanism, base_key, template={}) click to toggle source

Derives a key from a base key, creating a new key object.

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [PKCS11::Object] base_key key to derive @param [Hash] template Attributes of the object to create. @return [PKCS11::Object] key object of the new created key. @example Derive a AES key by XORing with some derivation data

deriv_data = "\0"*16
new_key = session.derive_key( {CKM_XOR_BASE_AND_DATA => {:pData => deriv_data}}, secret_key,
  :CLASS=>CKO_SECRET_KEY, :KEY_TYPE=>CKK_AES, :VALUE_LEN=>16, :ENCRYPT=>true )
# File lib/pkcs11/session.rb, line 718
def C_DeriveKey(mechanism, base_key, template={})
  obj = @pk.C_DeriveKey(@sess, to_mechanism(mechanism), base_key, to_attributes(template))
  Object.new @pk, @sess, obj
end
Also aliased as: derive_key
C_Digest(data, out_size=nil) click to toggle source

Digests data in a single part.

See {Session#digest} for convenience. @param [Integer, nil] out_size The buffer size for output data provided to the

library. If nil, size is determined automatically.

@return [String]

# File lib/pkcs11/session.rb, line 387
def C_Digest(data, out_size=nil)
  @pk.C_Digest(@sess, data, out_size)
end
C_DigestEncryptUpdate(data, out_size=nil) click to toggle source

Continues multiple-part digest and encryption operations, processing another data part.

Digest and encryption operations must both be active (they must have been initialized with {Session#C_DigestInit} and {Session#C_EncryptInit}, respectively). This function may be called any number of times in succession, and may be interspersed with {Session#C_DigestUpdate}, {Session#C_DigestKey}, and {Session#C_EncryptUpdate} calls.

# File lib/pkcs11/session.rb, line 607
def C_DigestEncryptUpdate(data, out_size=nil)
  @pk.C_DigestEncryptUpdate(@sess, data, out_size)
end
C_DigestFinal(out_size=nil) click to toggle source

Finishes a multiple-part message-digesting operation, returning the message digest as String.

See {Session#digest} for convenience. @param [Integer, nil] out_size The buffer size for output data provided to the

library. If nil, size is determined automatically.

@return [String]

# File lib/pkcs11/session.rb, line 419
def C_DigestFinal(out_size=nil)
  @pk.C_DigestFinal(@sess, out_size)
end
C_DigestInit(mechanism) click to toggle source

Initializes a message-digesting operation.

See {Session#digest} for convenience. @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 377
def C_DigestInit(mechanism)
  @pk.C_DigestInit(@sess, to_mechanism(mechanism))
  self
end
C_DigestKey(key) click to toggle source

Continues a multiple-part message-digesting operation by digesting the value of a secret key.

See {Session#digest} for convenience.

The message-digesting operation must have been initialized with {Session#C_DigestInit}. Calls to this function and {Session#C_DigestUpdate} may be interspersed any number of times in any order. @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 408
def C_DigestKey(key)
  @pk.C_DigestKey(@sess, key)
  self
end
C_DigestUpdate(data) click to toggle source

Continues a multiple-part message-digesting operation, processing another data part.

See {Session#digest} for convenience. @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 395
def C_DigestUpdate(data)
  @pk.C_DigestUpdate(@sess, data)
  self
end
C_Encrypt(data, out_size=nil) click to toggle source

Encrypts single-part data.

See {Session#encrypt} for convenience @param [Integer, nil] out_size The buffer size for output data provided to the

library. If nil, size is determined automatically.

@return [String]

# File lib/pkcs11/session.rb, line 267
def C_Encrypt(data, out_size=nil)
  @pk.C_Encrypt(@sess, data, out_size)
end
C_EncryptFinal(out_size=nil) click to toggle source

Finishes a multiple-part encryption operation.

See {Session#encrypt} for convenience @param [Integer, nil] out_size The buffer size for output data provided to the

library. If nil, size is determined automatically.

@return [String]

# File lib/pkcs11/session.rb, line 286
def C_EncryptFinal(out_size=nil)
  @pk.C_EncryptFinal(@sess, out_size)
end
C_EncryptInit(mechanism, key) click to toggle source

Initializes an encryption operation.

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism the encryption mechanism @param [PKCS11::Object] key the object handle of the encryption key. @return [PKCS11::Session]

See {Session#encrypt} for convenience

The CKA_ENCRYPT attribute of the encryption key, which indicates whether the key supports encryption, must be true.

After calling {Session#C_EncryptInit}, the application can either call {Session#C_Encrypt} to encrypt data in a single part; or call {Session#C_EncryptUpdate} zero or more times, followed by {Session#C_EncryptFinal}, to encrypt data in multiple parts. The encryption operation is active until the application uses a call to {Session#C_Encrypt} or {Session#C_EncryptFinal} to actually obtain the final piece of ciphertext. To process additional data (in single or multiple parts), the application must call {Session#C_EncryptInit} again.

# File lib/pkcs11/session.rb, line 257
def C_EncryptInit(mechanism, key)
  @pk.C_EncryptInit(@sess, to_mechanism(mechanism), key)
  self
end
C_EncryptUpdate(data, out_size=nil) click to toggle source

Continues a multiple-part encryption operation, processing another data part.

See {Session#encrypt} for convenience @param [Integer, nil] out_size The buffer size for output data provided to the

library. If nil, size is determined automatically.

@return [String]

# File lib/pkcs11/session.rb, line 277
def C_EncryptUpdate(data, out_size=nil)
  @pk.C_EncryptUpdate(@sess, data, out_size)
end
C_FindObjects(max_count) click to toggle source

Continues a search for token and session objects that match a template, obtaining additional object handles.

See {Session#find_objects} for convenience @return [Array<PKCS11::Object>] Returns an array of Object instances.

# File lib/pkcs11/session.rb, line 91
def C_FindObjects(max_count)
  objs = @pk.C_FindObjects(@sess, max_count)
  objs.map{|obj| Object.new @pk, @sess, obj }
end
C_FindObjectsFinal() click to toggle source

Terminates a search for token and session objects.

See {Session#find_objects} for convenience @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 100
def C_FindObjectsFinal
  @pk.C_FindObjectsFinal(@sess)
  self
end
C_FindObjectsInit(find_template={}) click to toggle source

Initializes a search for token and session objects that match a template.

See {Session#find_objects} for convenience. @param [Hash] find_template points to a search template that

specifies the attribute values to match

The matching criterion is an exact byte-for-byte match with all attributes in the template. Use empty Hash to find all objects. @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 81
def C_FindObjectsInit(find_template={})
  @pk.C_FindObjectsInit(@sess, to_attributes(find_template))
  self
end
C_GenerateKey(mechanism, template={}) click to toggle source

Generates a secret key Object or set of domain parameters, creating a new Object.

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [Hash] template Attributes of the key to create. @return [PKCS11::Object] key Object of the new created key. @example generate 112 bit DES key

key = session.generate_key(:DES2_KEY_GEN,
  {:ENCRYPT=>true, :WRAP=>true, :DECRYPT=>true, :UNWRAP=>true})
# File lib/pkcs11/session.rb, line 653
def C_GenerateKey(mechanism, template={})
  obj = @pk.C_GenerateKey(@sess, to_mechanism(mechanism), to_attributes(template))
  Object.new @pk, @sess, obj
end
Also aliased as: generate_key
C_GenerateKeyPair(mechanism, pubkey_template={}, privkey_template={}) click to toggle source

Generates a public/private key pair, creating new key Object instances.

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [Hash] pubkey_template Attributes of the public key to create. @param [Hash] privkey_template Attributes of the private key to create. @return [Array<PKCS11::Object>] an two-items array of new created public and private key Object. @example

pub_key, priv_key = session.generate_key_pair(:RSA_PKCS_KEY_PAIR_GEN,
  {:ENCRYPT=>true, :VERIFY=>true, :WRAP=>true, :MODULUS_BITS=>768, :PUBLIC_EXPONENT=>3},
  {:SUBJECT=>'test', :ID=>"ID", :DECRYPT=>true, :SIGN=>true, :UNWRAP=>true})
# File lib/pkcs11/session.rb, line 669
def C_GenerateKeyPair(mechanism, pubkey_template={}, privkey_template={})
  objs = @pk.C_GenerateKeyPair(@sess, to_mechanism(mechanism), to_attributes(pubkey_template), to_attributes(privkey_template))
  objs.map{|obj| Object.new @pk, @sess, obj }
end
Also aliased as: generate_key_pair
C_GenerateRandom(out_size) click to toggle source

Generates random or pseudo-random data.

@param [Integer] out_size @return [String] random or pseudo-random binary data of out_size bytes.

# File lib/pkcs11/session.rb, line 738
def C_GenerateRandom(out_size)
  @pk.C_GenerateRandom(@sess, out_size)
end
Also aliased as: generate_random
C_GetOperationState() click to toggle source

Obtains a copy of the cryptographic operations state of a session, encoded as a string of bytes. @return [String] @see Session#C_SetOperationState

# File lib/pkcs11/session.rb, line 747
def C_GetOperationState
  @pk.C_GetOperationState(@sess)
end
Also aliased as: get_operation_state
C_GetSessionInfo() click to toggle source

Obtains information about a session. @return [CK_SESSION_INFO]

# File lib/pkcs11/session.rb, line 67
def C_GetSessionInfo()
  @pk.C_GetSessionInfo(@sess)
end
Also aliased as: info
C_InitPIN(pin) click to toggle source

Initializes the normal user's PIN. This standard allows PIN values to contain any valid UTF8 character, but the token may impose subset restrictions.

@param [String] pin @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 164
def C_InitPIN(pin)
  @pk.C_InitPIN(@sess, pin)
  self
end
Also aliased as: init_pin
C_Login(user_type, pin) click to toggle source

Logs a user into a token. @param [Integer, Symbol] user_type is the user type CKU_*; @param [String] pin is the user's PIN. @return [PKCS11::Session]

When the user type is either CKU_SO or CKU_USER, if the call succeeds, each of the application's sessions will enter either the “R/W SO Functions” state, the “R/W User Functions” state, or the “R/O User Functions” state. If the user type is CKU_CONTEXT_SPECIFIC , the behavior of C_Login depends on the context in which it is called. Improper use of this user type will raise CKR_OPERATION_NOT_INITIALIZED.

# File lib/pkcs11/session.rb, line 39
def C_Login(user_type, pin)
  @pk.C_Login(@sess, string_to_handle('CKU_', user_type), pin)
  self
end
Also aliased as: login
C_Logout() click to toggle source

Logs a user out from a token.

Depending on the current user type, if the call succeeds, each of the application's sessions will enter either the “R/W Public Session” state or the “R/O Public Session” state. @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 51
def C_Logout()
  @pk.C_Logout(@sess)
  self
end
Also aliased as: logout
C_SeedRandom(data) click to toggle source

Mixes additional seed material into the token's random number generator. @param [String] entropy data @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 728
def C_SeedRandom(data)
  @pk.C_SeedRandom(@sess, data)
  self
end
Also aliased as: seed_random
C_SetOperationState(state, enc_key=nil, auth_key=nil) click to toggle source

Restores the cryptographic operations state of a session from a string of bytes obtained with {Session#C_GetOperationState}.

@param [String] state previously stored session state @param [PKCS11::Object] encryption key for sessions stored without keys @param [PKCS11::Object] authentication key for sessions stored without keys @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 759
def C_SetOperationState(state, enc_key=nil, auth_key=nil)
  @pk.C_SetOperationState(@sess, state, enc_key||0, auth_key||0)
  self
end
Also aliased as: set_operation_state
C_SetPIN(old_pin, new_pin) click to toggle source

Modifies the PIN of the user that is currently logged in, or the CKU_USER PIN if the session is not logged in.

@param [String] old_pin @param [String] new_pin @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 176
def C_SetPIN(old_pin, new_pin)
  @pk.C_SetPIN(@sess, old_pin, new_pin)
  self
end
Also aliased as: set_pin
C_Sign(data, out_size=nil) click to toggle source

Signs data in a single part, where the signature is an appendix to the data.

See {Session#sign} for convenience. @return [String] message signature

# File lib/pkcs11/session.rb, line 464
def C_Sign(data, out_size=nil)
  @pk.C_Sign(@sess, data, out_size)
end
C_SignEncryptUpdate(data, out_size=nil) click to toggle source

Continues a multiple-part combined signature and encryption operation, processing another data part.

Signature and encryption operations must both be active (they must have been initialized with {Session#C_SignInit} and {Session#C_EncryptInit}, respectively). This function may be called any number of times in succession, and may be interspersed with {Session#C_SignUpdate} and {Session#C_EncryptUpdate} calls.

# File lib/pkcs11/session.rb, line 629
def C_SignEncryptUpdate(data, out_size=nil)
  @pk.C_SignEncryptUpdate(@sess, data, out_size)
end
C_SignFinal(out_size=nil) click to toggle source

Finishes a multiple-part signature operation, returning the signature.

See {Session#sign} for convenience. @return [String] message signature

# File lib/pkcs11/session.rb, line 480
def C_SignFinal(out_size=nil)
  @pk.C_SignFinal(@sess, out_size)
end
C_SignInit(mechanism, key) click to toggle source

Initializes a signature operation, where the signature is an appendix to the data.

See {Session#sign} for convenience. @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 456
def C_SignInit(mechanism, key)
  @pk.C_SignInit(@sess, to_mechanism(mechanism), key)
  self
end
C_SignRecover(data, out_size=nil) click to toggle source

Signs data in a single operation, where the data can be recovered from the signature.

See {Session#sign_recover} for convenience.

# File lib/pkcs11/session.rb, line 557
def C_SignRecover(data, out_size=nil)
  @pk.C_SignRecover(@sess, data, out_size)
end
C_SignRecoverInit(mechanism, key) click to toggle source

Initializes a signature operation, where the data can be recovered from the signature

See {Session#sign_recover} for convenience.

# File lib/pkcs11/session.rb, line 549
def C_SignRecoverInit(mechanism, key)
  @pk.C_SignRecoverInit(@sess, to_mechanism(mechanism), key)
  self
end
C_SignUpdate(data) click to toggle source

Continues a multiple-part signature operation, processing another data part.

See {Session#sign} for convenience. @return [PKCS11::Session]

# File lib/pkcs11/session.rb, line 472
def C_SignUpdate(data)
  @pk.C_SignUpdate(@sess, data)
  self
end
C_UnwrapKey(mechanism, wrapping_key, wrapped_key, template={}) click to toggle source

Unwraps (i.e. decrypts) a wrapped key, creating a new private key or secret key object.

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [PKCS11::Object] wrapping_key wrapping key @param [String] wrapped_key key data of the wrapped key @return [PKCS11::Object] key object of the new created key. @see Session#C_WrapKey @example

unwrapped_key = session.unwrap_key(:DES3_ECB, secret_key, wrapped_key_value,
    :CLASS=>CKO_SECRET_KEY, :KEY_TYPE=>CKK_DES2, :ENCRYPT=>true, :DECRYPT=>true)
# File lib/pkcs11/session.rb, line 702
def C_UnwrapKey(mechanism, wrapping_key, wrapped_key, template={})
  obj = @pk.C_UnwrapKey(@sess, to_mechanism(mechanism), wrapping_key, wrapped_key, to_attributes(template))
  Object.new @pk, @sess, obj
end
Also aliased as: unwrap_key
C_Verify(data, out_size=nil) click to toggle source

Verifies a signature in a single-part operation, where the signature is an appendix to the data.

See {Session#verify} for convenience.

# File lib/pkcs11/session.rb, line 511
def C_Verify(data, out_size=nil)
  @pk.C_Verify(@sess, data, out_size)
end
C_VerifyFinal(out_size=nil) click to toggle source

Finishes a multiple-part verification operation, checking the signature.

See {Session#verify} for convenience. @return [Boolean] true for valid signature.

# File lib/pkcs11/session.rb, line 525
def C_VerifyFinal(out_size=nil)
  @pk.C_VerifyFinal(@sess, out_size)
end
C_VerifyInit(mechanism, key) click to toggle source

Initializes a verification operation, where the signature is an appendix to the data.

See {Session#verify} for convenience.

# File lib/pkcs11/session.rb, line 504
def C_VerifyInit(mechanism, key)
  @pk.C_VerifyInit(@sess, to_mechanism(mechanism), key)
end
C_VerifyRecover(signature, out_size=nil) click to toggle source

Verifies a signature in a single-part operation, where the data is recovered from the signature.

See {Session#verify_recover} for convenience.

# File lib/pkcs11/session.rb, line 585
def C_VerifyRecover(signature, out_size=nil)
  @pk.C_VerifyRecover(@sess, signature, out_size=nil)
end
C_VerifyRecoverInit(mechanism, key) click to toggle source

Initializes a signature verification operation, where the data can be recovered from the signature

See {Session#verify_recover} for convenience.

# File lib/pkcs11/session.rb, line 578
def C_VerifyRecoverInit(mechanism, key)
  @pk.C_VerifyRecoverInit(@sess, to_mechanism(mechanism), key)
end
C_VerifyUpdate(data) click to toggle source

Continues a multiple-part verification operation, processing another data part.

See {Session#verify} for convenience.

# File lib/pkcs11/session.rb, line 518
def C_VerifyUpdate(data)
  @pk.C_VerifyUpdate(@sess, data)
end
C_WrapKey(mechanism, wrapping_key, wrapped_key, out_size=nil) click to toggle source

Wraps (i.e., encrypts) a private or secret key.

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [PKCS11::Object] wrapping_key wrapping key @param [PKCS11::Object] wrapped_key key to wrap @return [String] the encrypted binary data. @see Session#C_UnwrapKey @example Wrapping a secret key

wrapped_key_value = session.wrap_key(:DES3_ECB, secret_key, secret_key)

@example Wrapping a private key

wrapped_key_value = session.wrap_key({:DES3_CBC_PAD=>"\0"*8}, secret_key, rsa_priv_key)
# File lib/pkcs11/session.rb, line 686
def C_WrapKey(mechanism, wrapping_key, wrapped_key, out_size=nil)
  @pk.C_WrapKey(@sess, to_mechanism(mechanism), wrapping_key, wrapped_key, out_size)
end
Also aliased as: wrap_key
close()
Alias for: C_CloseSession
create_object(template={})
Alias for: C_CreateObject
decrypt(mechanism, key, data=nil, &block) click to toggle source

Convenience method for the {Session#C_DecryptInit}, {Session#C_DecryptUpdate}, {Session#C_DecryptFinal} call flow.

@see Session#encrypt

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [PKCS11::Object] key used key @param [String] data data to decrypt @yield [PKCS11::Session::Cipher] Cipher object for processing data parts @return [String] the final part of the encryption operation. @example Decrypt data previously encrypted with a RSA pulic key

plaintext2 = session.decrypt( :RSA_PKCS, rsa_priv_key, cryptogram)
# File lib/pkcs11/session.rb, line 368
def decrypt(mechanism, key, data=nil, &block)
  common_crypt(:C_DecryptInit, :C_DecryptUpdate, :C_DecryptFinal, :C_Decrypt,
               mechanism, key, data, &block)
end
derive_key(mechanism, base_key, template={})
Alias for: C_DeriveKey
digest(mechanism, data=nil) { |digest_cipher(proc{|data_| C_DigestUpdate(data_)| ... } click to toggle source

Convenience method for the {Session#C_DigestInit}, {Session#C_DigestUpdate}, {Session#C_DigestKey}, {Session#C_DigestFinal} call flow.

@example

digest_string = session.digest( :SHA_1 ) do |cipher|
  cipher.update("key prefix")
  cipher.digest_key(some_key)
end

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [String] data data to digest @yield [PKCS11::Session::DigestCipher] Cipher object for processing data parts @return [String] final message digest @see Session#encrypt

# File lib/pkcs11/session.rb, line 436
def digest(mechanism, data=nil, &block)
  C_DigestInit(mechanism)
  if block_given?
    raise "data not nil, but block given" if data
    yield DigestCipher.new(proc{|data_|
      C_DigestUpdate(data_)
    }, proc{|key_|
      C_DigestKey(key_)
    })
    C_DigestFinal()
  else
    C_Digest(data)
  end
end
encrypt(mechanism, key, data=nil, &block) click to toggle source

Convenience method for the {Session#C_EncryptInit}, {Session#C_EncryptUpdate}, {Session#C_EncryptFinal} call flow.

If no block is given, the single part operation {Session#C_EncryptInit}, {Session#C_Encrypt} is called. If a block is given, the multi part operation ({Session#C_EncryptInit}, {Session#C_EncryptUpdate}, {Session#C_EncryptFinal}) is used. The given block is called once with a cipher object. There can be any number of {Cipher#update} calls within the block, each giving the encryption result of this part as String.

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [PKCS11::Object] key used key @param [String] data data to encrypt @yield [PKCS11::Session::Cipher] Cipher object for processing data parts @return [String] the final part of the encryption operation.

@example for using single part operation

iv = "12345678"
cryptogram = session.encrypt( {:DES_CBC_PAD=>iv}, key, "block 1block 2" )

@example for using multi part operation

iv = "12345678"
cryptogram = ''
cryptogram << session.encrypt( {:DES_CBC_PAD=>iv}, key ) do |cipher|
  cryptogram << cipher.update("block 1")
  cryptogram << cipher.update("block 2")
end

@example Calculating a key check value to a secret key

key_kcv = session.encrypt( :DES3_ECB, key, "\0"*8)
# File lib/pkcs11/session.rb, line 317
def encrypt(mechanism, key, data=nil, &block)
  common_crypt(:C_EncryptInit, :C_EncryptUpdate, :C_EncryptFinal, :C_Encrypt,
               mechanism, key, data, &block)
end
find_objects(template={}) { |obj| ... } click to toggle source

Convenience method for the {Session#C_FindObjectsInit}, {Session#C_FindObjects}, {Session#C_FindObjectsFinal} cycle.

  • If called with block, it iterates over all found objects.

  • If called without block, it returns with an array of all found Object instances.

@return [Array<PKCS11::Object>]

@example prints subject of all certificates stored in the token:

session.find_objects(:CLASS => PKCS11::CKO_CERTIFICATE) do |obj|
  p OpenSSL::X509::Name.new(obj[:SUBJECT])
end
# File lib/pkcs11/session.rb, line 115
def find_objects(template={})
  all_objs = [] unless block_given?
  C_FindObjectsInit(template)
  begin
    loop do
      objs = C_FindObjects(20)
      break if objs.empty?
      if block_given?
        objs.each{|obj| yield obj }
      else
        all_objs += objs
      end
    end
  ensure
    C_FindObjectsFinal()
  end
  return all_objs
end
generate_key(mechanism, template={})
Alias for: C_GenerateKey
generate_key_pair(mechanism, pubkey_template={}, privkey_template={})
Alias for: C_GenerateKeyPair
generate_random(out_size)
Alias for: C_GenerateRandom
get_operation_state()
Alias for: C_GetOperationState
info()
Alias for: C_GetSessionInfo
init_pin(pin)
Alias for: C_InitPIN
login(user_type, pin)
Alias for: C_Login
logout()
Alias for: C_Logout
seed_random(data)
Alias for: C_SeedRandom
set_operation_state(state, enc_key=nil, auth_key=nil)
Alias for: C_SetOperationState
set_pin(old_pin, new_pin)
Alias for: C_SetPIN
sign(mechanism, key, data=nil, &block) click to toggle source

Convenience method for the {Session#C_SignInit}, {Session#C_SignUpdate}, {Session#C_SignFinal} call flow.

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [PKCS11::Object] key used key @param [String] data data to sign @yield [PKCS11::Session::Cipher] Cipher object for processing data parts @return [String] signature @see Session#encrypt @example Sign a text by a RSA private key

signature = session.sign( :SHA1_RSA_PKCS, rsa_priv_key, "important text")
# File lib/pkcs11/session.rb, line 494
def sign(mechanism, key, data=nil, &block)
  common_crypt(:C_SignInit, :C_SignUpdate, :C_SignFinal, :C_Sign,
               mechanism, key, data, &block)
end
sign_recover(mechanism, key, data) click to toggle source

Convenience method for the {Session#C_SignRecoverInit}, {Session#C_SignRecover} call flow.

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [PKCS11::Object] key signature key @param [String] data data to be recovered @return [String] signature @see Session#verify_recover

# File lib/pkcs11/session.rb, line 568
def sign_recover(mechanism, key, data)
  C_SignRecoverInit(mechanism, key)
  C_SignRecover(data)
end
to_i()
Alias for: to_int
to_int() click to toggle source

The session handle. @return [Integer]

# File lib/pkcs11/session.rb, line 18
def to_int
  @sess
end
Also aliased as: to_i
unwrap_key(mechanism, wrapping_key, wrapped_key, template={})
Alias for: C_UnwrapKey
verify(mechanism, key, signature, data=nil, &block) click to toggle source

Convenience method for the {Session#C_VerifyInit}, {Session#C_VerifyUpdate}, {Session#C_VerifyFinal} call flow.

@see Session#encrypt @param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [PKCS11::Object] key used key @param [String] signature signature @param [String] data data to verify against signature @yield [PKCS11::Session::Cipher] Cipher object for processing data parts @return [Boolean] true for valid signature. @example

raise("wrong signature") unless session.verify(:SHA1_RSA_PKCS, rsa_pub_key, signature, plaintext)
# File lib/pkcs11/session.rb, line 540
def verify(mechanism, key, signature, data=nil, &block)
  common_verify(:C_VerifyInit, :C_VerifyUpdate, :C_VerifyFinal, :C_Verify,
               mechanism, key, signature, data, &block)
end
verify_recover(mechanism, key, signature) click to toggle source

Convenience method for the {Session#C_VerifyRecoverInit}, {Session#C_VerifyRecover} call flow.

@param [Hash, Symbol, Integer, PKCS11::CK_MECHANISM] mechanism used mechanism @param [PKCS11::Object] key verification key @return [String] recovered data @see Session#sign_recover

# File lib/pkcs11/session.rb, line 595
def verify_recover(mechanism, key, signature)
  C_VerifyRecoverInit(mechanism, key)
  C_VerifyRecover(signature)
end
wrap_key(mechanism, wrapping_key, wrapped_key, out_size=nil)
Alias for: C_WrapKey