Class: PKCS11::Session

Inherits:
Object
  • Object
show all
Defined in:
lib/pkcs11/session.rb

Overview

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).

Defined Under Namespace

Classes: Cipher, DigestCipher

Instance Method Summary collapse

Instance Method Details

#C_CloseSession ⇒ PKCS11::Session Also known as: close

Closes the session between an application and a token.

Returns:



59
60
61
62
 
# File 'lib/pkcs11/session.rb', line 59

def C_CloseSession()
  @pk.C_CloseSession(@sess)
  self
end

#C_CreateObject(template = {}) ⇒ PKCS11::Object Also known as: create_object

Creates a new Object based on given template.

If #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.

Examples:

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')

Parameters:

  • template (Hash) (defaults to: {}) —

    Attributes of the object to create.

Returns:



152
153
154
155
 
# 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

#C_Decrypt(data, out_size = nil) ⇒ String

Decrypts encrypted data in a single part.

See #decrypt for convenience.

Parameters:

  • out_size (Integer, nil) (defaults to: nil) —

    The buffer size for output data provided to the library. If nil, size is determined automatically.

Returns:

  • (String) 


334
335
336
 
# 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) ⇒ Object

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 #C_DecryptInit and #C_DigestInit, respectively). This function may be called any number of times in succession, and may be interspersed with #C_DecryptUpdate, #C_DigestUpdate, and #C_DigestKey calls.



618
619
620
 
# 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) ⇒ String

Finishes a multiple-part decryption operation.

See #decrypt for convenience.

Parameters:

  • out_size (Integer, nil) (defaults to: nil) —

    The buffer size for output data provided to the library. If nil, size is determined automatically.

Returns:

  • (String) 


353
354
355
 
# File 'lib/pkcs11/session.rb', line 353

def C_DecryptFinal(out_size=nil)
  @pk.C_DecryptFinal(@sess, out_size)
end

#C_DecryptInit(mechanism, key) ⇒ Object

Initializes a decryption operation.

See #decrypt for convenience and #C_EncryptInit for description.



325
326
327
 
# 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) ⇒ String

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

See #decrypt for convenience.

Parameters:

  • out_size (Integer, nil) (defaults to: nil) —

    The buffer size for output data provided to the library. If nil, size is determined automatically.

Returns:

  • (String) 


344
345
346
 
# 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) ⇒ Object

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 #C_DecryptInit and #C_VerifyInit, respectively). This function may be called any number of times in succession, and may be interspersed with #C_DecryptUpdate and #C_VerifyUpdate calls.



640
641
642
 
# 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 = {}) ⇒ PKCS11::Object Also known as: derive_key

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

Examples:

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 )

Parameters:

  • mechanism (Hash, Symbol, Integer, PKCS11::CK_MECHANISM) —

    used mechanism

  • base_key (PKCS11::Object) —

    key to derive

  • template (Hash) (defaults to: {}) —

    Attributes of the object to create.

Returns:



718
719
720
721
 
# 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

#C_Digest(data, out_size = nil) ⇒ String

Digests data in a single part.

See #digest for convenience.

Parameters:

  • out_size (Integer, nil) (defaults to: nil) —

    The buffer size for output data provided to the library. If nil, size is determined automatically.

Returns:

  • (String) 


387
388
389
 
# 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) ⇒ Object

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 #C_DigestInit and #C_EncryptInit, respectively). This function may be called any number of times in succession, and may be interspersed with #C_DigestUpdate, #C_DigestKey, and #C_EncryptUpdate calls.



607
608
609
 
# 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) ⇒ String

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

See #digest for convenience.

Parameters:

  • out_size (Integer, nil) (defaults to: nil) —

    The buffer size for output data provided to the library. If nil, size is determined automatically.

Returns:

  • (String) 


419
420
421
 
# File 'lib/pkcs11/session.rb', line 419

def C_DigestFinal(out_size=nil)
  @pk.C_DigestFinal(@sess, out_size)
end

#C_DigestInit(mechanism) ⇒ PKCS11::Session

Initializes a message-digesting operation.

See #digest for convenience.

Returns:



377
378
379
380
 
# File 'lib/pkcs11/session.rb', line 377

def C_DigestInit(mechanism)
  @pk.C_DigestInit(@sess, to_mechanism(mechanism))
  self
end

#C_DigestKey(key) ⇒ PKCS11::Session

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

See #digest for convenience.

The message-digesting operation must have been initialized with #C_DigestInit. Calls to this function and #C_DigestUpdate may be interspersed any number of times in any order.

Returns:



408
409
410
411
 
# File 'lib/pkcs11/session.rb', line 408

def C_DigestKey(key)
  @pk.C_DigestKey(@sess, key)
  self
end

#C_DigestUpdate(data) ⇒ PKCS11::Session

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

See #digest for convenience.

Returns:



395
396
397
398
 
# File 'lib/pkcs11/session.rb', line 395

def C_DigestUpdate(data)
  @pk.C_DigestUpdate(@sess, data)
  self
end

#C_Encrypt(data, out_size = nil) ⇒ String

Encrypts single-part data.

See #encrypt for convenience

Parameters:

  • out_size (Integer, nil) (defaults to: nil) —

    The buffer size for output data provided to the library. If nil, size is determined automatically.

Returns:

  • (String) 


267
268
269
 
# 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) ⇒ String

Finishes a multiple-part encryption operation.

See #encrypt for convenience

Parameters:

  • out_size (Integer, nil) (defaults to: nil) —

    The buffer size for output data provided to the library. If nil, size is determined automatically.

Returns:

  • (String) 


286
287
288
 
# File 'lib/pkcs11/session.rb', line 286

def C_EncryptFinal(out_size=nil)
  @pk.C_EncryptFinal(@sess, out_size)
end

#C_EncryptInit(mechanism, key) ⇒ PKCS11::Session

Initializes an encryption operation.

See #encrypt for convenience

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

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

Parameters:

Returns:



257
258
259
260
 
# 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) ⇒ String

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

See #encrypt for convenience

Parameters:

  • out_size (Integer, nil) (defaults to: nil) —

    The buffer size for output data provided to the library. If nil, size is determined automatically.

Returns:

  • (String) 


277
278
279
 
# 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) ⇒ Array<PKCS11::Object>

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

See #find_objects for convenience

Returns:



91
92
93
94
 
# 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 ⇒ PKCS11::Session

Terminates a search for token and session objects.

See #find_objects for convenience

Returns:



100
101
102
103
 
# File 'lib/pkcs11/session.rb', line 100

def C_FindObjectsFinal
  @pk.C_FindObjectsFinal(@sess)
  self
end

#C_FindObjectsInit(find_template = {}) ⇒ PKCS11::Session

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

See #find_objects for convenience. The matching criterion is an exact byte-for-byte match with all attributes in the template. Use empty Hash to find all objects.

Parameters:

  • find_template (Hash) (defaults to: {}) —

    points to a search template that specifies the attribute values to match

Returns:



81
82
83
84
 
# 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 = {}) ⇒ PKCS11::Object Also known as: generate_key

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

Examples:

generate 112 bit DES key

key = session.generate_key(:DES2_KEY_GEN,
  {ENCRYPT: true, WRAP: true, DECRYPT: true, UNWRAP: true})

Parameters:

  • mechanism (Hash, Symbol, Integer, PKCS11::CK_MECHANISM) —

    used mechanism

  • template (Hash) (defaults to: {}) —

    Attributes of the key to create.

Returns:



653
654
655
656
 
# 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

#C_GenerateKeyPair(mechanism, pubkey_template = {}, privkey_template = {}) ⇒ Array<PKCS11::Object> Also known as: generate_key_pair

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

Examples:

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})

Parameters:

  • mechanism (Hash, Symbol, Integer, PKCS11::CK_MECHANISM) —

    used mechanism

  • pubkey_template (Hash) (defaults to: {}) —

    Attributes of the public key to create.

  • privkey_template (Hash) (defaults to: {}) —

    Attributes of the private key to create.

Returns:

  • (Array<PKCS11::Object>) —

    an two-items array of new created public and private key Object.



669
670
671
672
 
# 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

#C_GenerateRandom(out_size) ⇒ String Also known as: generate_random

Generates random or pseudo-random data.

Parameters:

  • out_size (Integer)

Returns:

  • (String) —

    random or pseudo-random binary data of out_size bytes.



738
739
740
 
# File 'lib/pkcs11/session.rb', line 738

def C_GenerateRandom(out_size)
  @pk.C_GenerateRandom(@sess, out_size)
end

#C_GetOperationState ⇒ String Also known as: get_operation_state

Obtains a copy of the cryptographic operations state of a session, encoded as a string of bytes.

Returns:

  • (String)

See Also:



747
748
749
 
# File 'lib/pkcs11/session.rb', line 747

def C_GetOperationState
  @pk.C_GetOperationState(@sess)
end

#C_GetSessionInfo ⇒ CK_SESSION_INFO Also known as: info

Obtains information about a session.

Returns:



67
68
69
 
# File 'lib/pkcs11/session.rb', line 67

def C_GetSessionInfo()
  @pk.C_GetSessionInfo(@sess)
end

#C_InitPIN(pin) ⇒ PKCS11::Session Also known as: init_pin

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

Parameters:

  • pin (String)

Returns:



164
165
166
167
 
# File 'lib/pkcs11/session.rb', line 164

def C_InitPIN(pin)
  @pk.C_InitPIN(@sess, pin)
  self
end

#C_Login(user_type, pin) ⇒ PKCS11::Session Also known as: login

Logs a user into a token. 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.

Parameters:

  • user_type (Integer, Symbol) —

    is the user type CKU_*;

  • pin (String) —

    is the user’s PIN.

Returns:



39
40
41
42
 
# 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

#C_Logout ⇒ PKCS11::Session Also known as: logout

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.

Returns:



51
52
53
54
 
# File 'lib/pkcs11/session.rb', line 51

def C_Logout()
  @pk.C_Logout(@sess)
  self
end

#C_SeedRandom(data) ⇒ PKCS11::Session Also known as: seed_random

Mixes additional seed material into the token’s random number generator.

Parameters:

  • entropy (String) —

    data

Returns:



728
729
730
731
 
# File 'lib/pkcs11/session.rb', line 728

def C_SeedRandom(data)
  @pk.C_SeedRandom(@sess, data)
  self
end

#C_SetOperationState(state, enc_key = nil, auth_key = nil) ⇒ PKCS11::Session Also known as: set_operation_state

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

Parameters:

  • state (String) —

    previously stored session state

  • encryption (PKCS11::Object) —

    key for sessions stored without keys

  • authentication (PKCS11::Object) —

    key for sessions stored without keys

Returns:



759
760
761
762
 
# 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

#C_SetPIN(old_pin, new_pin) ⇒ PKCS11::Session Also known as: set_pin

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

Parameters:

  • old_pin (String)
  • new_pin (String)

Returns:



176
177
178
179
 
# File 'lib/pkcs11/session.rb', line 176

def C_SetPIN(old_pin, new_pin)
  @pk.C_SetPIN(@sess, old_pin, new_pin)
  self
end

#C_Sign(data, out_size = nil) ⇒ String

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

See #sign for convenience.

Returns:

  • (String) —

    message signature



464
465
466
 
# 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) ⇒ Object

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 #C_SignInit and #C_EncryptInit, respectively). This function may be called any number of times in succession, and may be interspersed with #C_SignUpdate and #C_EncryptUpdate calls.



629
630
631
 
# 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) ⇒ String

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

See #sign for convenience.

Returns:

  • (String) —

    message signature



480
481
482
 
# File 'lib/pkcs11/session.rb', line 480

def C_SignFinal(out_size=nil)
  @pk.C_SignFinal(@sess, out_size)
end

#C_SignInit(mechanism, key) ⇒ PKCS11::Session

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

See #sign for convenience.

Returns:



456
457
458
459
 
# 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) ⇒ Object

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

See #sign_recover for convenience.



557
558
559
 
# 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) ⇒ Object

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

See #sign_recover for convenience.



549
550
551
552
 
# 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) ⇒ PKCS11::Session

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

See #sign for convenience.

Returns:



472
473
474
475
 
# 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 = {}) ⇒ PKCS11::Object Also known as: unwrap_key

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

Examples:

unwrapped_key = session.unwrap_key(:DES3_ECB, secret_key, wrapped_key_value,
    CLASS: CKO_SECRET_KEY, KEY_TYPE: CKK_DES2, ENCRYPT: true, DECRYPT: true)

Parameters:

  • mechanism (Hash, Symbol, Integer, PKCS11::CK_MECHANISM) —

    used mechanism

  • wrapping_key (PKCS11::Object) —

    wrapping key

  • wrapped_key (String) —

    key data of the wrapped key

Returns:

See Also:



702
703
704
705
 
# 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

#C_Verify(data, out_size = nil) ⇒ Object

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

See #verify for convenience.



511
512
513
 
# 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) ⇒ Boolean

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

See #verify for convenience.

Returns:

  • (Boolean) —

    true for valid signature.



525
526
527
 
# File 'lib/pkcs11/session.rb', line 525

def C_VerifyFinal(out_size=nil)
  @pk.C_VerifyFinal(@sess, out_size)
end

#C_VerifyInit(mechanism, key) ⇒ Object

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

See #verify for convenience.



504
505
506
 
# 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) ⇒ Object

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

See #verify_recover for convenience.



585
586
587
 
# 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) ⇒ Object

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

See #verify_recover for convenience.



578
579
580
 
# File 'lib/pkcs11/session.rb', line 578

def C_VerifyRecoverInit(mechanism, key)
  @pk.C_VerifyRecoverInit(@sess, to_mechanism(mechanism), key)
end

#C_VerifyUpdate(data) ⇒ Object

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

See #verify for convenience.



518
519
520
 
# 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) ⇒ String Also known as: wrap_key

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

Examples:

Wrapping a secret key

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

Wrapping a private key

wrapped_key_value = session.wrap_key({DES3_CBC_PAD: "\0"*8}, secret_key, rsa_priv_key)

Parameters:

Returns:

  • (String) —

    the encrypted binary data.

See Also:



686
687
688
 
# 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

#decrypt(mechanism, key, data = nil) {|PKCS11::Session::Cipher| ... } ⇒ String

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

Examples:

Decrypt data previously encrypted with a RSA pulic key

plaintext2 = session.decrypt( :RSA_PKCS, rsa_priv_key, cryptogram)

Parameters:

Yields:

Returns:

  • (String) —

    the final part of the encryption operation.

See Also:



368
369
370
371
 
# 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

#digest(mechanism, data = nil) {|PKCS11::Session::DigestCipher| ... } ⇒ String

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

Examples:

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

Parameters:

  • mechanism (Hash, Symbol, Integer, PKCS11::CK_MECHANISM) —

    used mechanism

  • data (String) (defaults to: nil) —

    data to digest

Yields:

Returns:

  • (String) —

    final message digest

See Also:



436
437
438
439
440
441
442
443
444
445
446
447
448
449
 
# 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) {|PKCS11::Session::Cipher| ... } ⇒ String

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

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

Examples:

for using single part operation

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

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

Calculating a key check value to a secret key

key_kcv = session.encrypt( :DES3_ECB, key, "\0"*8)

Parameters:

Yields:

Returns:

  • (String) —

    the final part of the encryption operation.



317
318
319
320
 
# 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 = {}) ⇒ Array<PKCS11::Object>

Convenience method for the #C_FindObjectsInit, #C_FindObjects, #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.

Examples:

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

Returns:



115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# 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

#sign(mechanism, key, data = nil) {|PKCS11::Session::Cipher| ... } ⇒ String

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

Examples:

Sign a text by a RSA private key

signature = session.sign( :SHA1_RSA_PKCS, rsa_priv_key, "important text")

Parameters:

Yields:

Returns:

  • (String) —

    signature

See Also:



494
495
496
497
 
# 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) ⇒ String

Convenience method for the #C_SignRecoverInit, #C_SignRecover call flow.

Parameters:

Returns:

  • (String) —

    signature

See Also:



568
569
570
571
 
# File 'lib/pkcs11/session.rb', line 568

def sign_recover(mechanism, key, data)
  C_SignRecoverInit(mechanism, key)
  C_SignRecover(data)
end

#to_int ⇒ Integer Also known as: to_i

The session handle.

Returns:

  • (Integer) 


18
19
20
 
# File 'lib/pkcs11/session.rb', line 18

def to_int
  @sess
end

#verify(mechanism, key, signature, data = nil) {|PKCS11::Session::Cipher| ... } ⇒ Boolean

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

Examples:

raise("wrong signature") unless session.verify(:SHA1_RSA_PKCS, rsa_pub_key, signature, plaintext)

Parameters:

  • mechanism (Hash, Symbol, Integer, PKCS11::CK_MECHANISM) —

    used mechanism

  • key (PKCS11::Object) —

    used key

  • signature (String) —

    signature

  • data (String) (defaults to: nil) —

    data to verify against signature

Yields:

Returns:

  • (Boolean) —

    true for valid signature.

See Also:



540
541
542
543
 
# 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) ⇒ String

Convenience method for the #C_VerifyRecoverInit, #C_VerifyRecover call flow.

Parameters:

Returns:

  • (String) —

    recovered data

See Also:



595
596
597
598
 
# File 'lib/pkcs11/session.rb', line 595

def verify_recover(mechanism, key, signature)
  C_VerifyRecoverInit(mechanism, key)
  C_VerifyRecover(signature)
end