Class: Botan::Cipher

Inherits:
Object
  • Object
show all
Defined in:
lib/botan/cipher.rb

Overview

Cipher

Examples

examples/cipher.rb

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(algo, encrypt:) ⇒ Cipher

Prefer the shortcuts encryption and decryption instead.

Parameters:

  • algo (String) —

    the algorithm to use (example: AES-128/CTR-BE)

  • encrypt (Boolean) —

    true if this will be used for encryption, false if it will be used for decryption.

Raises:



24
25
26
27
28
29
30
31
 
# File 'lib/botan/cipher.rb', line 24

def initialize(algo, encrypt:)
  flags = encrypt ? 0 : 1
  ptr = FFI::MemoryPointer.new(:pointer)
  Botan.call_ffi(:botan_cipher_init, ptr, algo, flags)
  ptr = ptr.read_pointer
  raise Botan::Error, 'botan_cipher_init returned NULL' if ptr.null?
  @ptr = FFI::AutoPointer.new(ptr, self.class.method(:destroy))
end

Class Method Details

.decryption(algo) ⇒ Botan::Cipher

Creates a new cipher instance for decryption.

Parameters:

  • algo (String) —

    the algorithm to use (example: AES-128/CTR-BE)

Returns:



50
51
52
 
# File 'lib/botan/cipher.rb', line 50

def self.decryption(algo)
  Cipher.new(algo, encrypt: false)
end

.destroy(ptr) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



34
35
36
 
# File 'lib/botan/cipher.rb', line 34

def self.destroy(ptr)
  LibBotan.botan_cipher_destroy(ptr)
end

.encryption(algo) ⇒ Botan::Cipher

Creates a new cipher instance for encryption.

Parameters:

  • algo (String) —

    the algorithm to use (example: AES-128/CTR-BE)

Returns:



42
43
44
 
# File 'lib/botan/cipher.rb', line 42

def self.encryption(algo)
  Cipher.new(algo, encrypt: true)
end

Instance Method Details

#auth_data=(ad) ⇒ Object

Sets the associated data when using AEAD modes.

This should be called after #key= and before #iv=.

Parameters:

  • ad (String) —

    the associated data



145
146
147
148
 
# File 'lib/botan/cipher.rb', line 145

def auth_data=(ad)
  ad_buf = FFI::MemoryPointer.from_data(ad)
  Botan.call_ffi(:botan_cipher_set_associated_data, @ptr, ad_buf, ad.size)
end

#authenticated? ⇒ Boolean

Determines whether this is an AEAD mode.

Returns:

  • (Boolean) —

    true if this is an AEAD mode



98
99
100
 
# File 'lib/botan/cipher.rb', line 98

def authenticated?
  tag_length.positive?
end

#default_nonce_length ⇒ Integer

Retrieves the default nonce length for the cipher.

Returns:

  • (Integer) 


57
58
59
60
61
 
# File 'lib/botan/cipher.rb', line 57

def default_nonce_length
  length_ptr = FFI::MemoryPointer.new(:size_t)
  Botan.call_ffi(:botan_cipher_get_default_nonce_length, @ptr, length_ptr)
  length_ptr.read(:size_t)
end

#finish(data = nil) ⇒ String

Finalize the message processing.

It is perfectly valid to skip #update and pass your entire message here.

Note: Some ciphers may require a final piece of data of a certain size. See minimum_final_size in the Botan documentation.

Parameters:

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

    the data, if any

Returns:

  • (String) —

    the ciphertext or plaintext



169
170
171
 
# File 'lib/botan/cipher.rb', line 169

def finish(data = nil)
  _update(data, final: true)
end

#inspect ⇒ Object 



173
174
175
 
# File 'lib/botan/cipher.rb', line 173

def inspect
  Botan.inspect_ptr(self)
end

#iv=(iv) ⇒ Object

Sets the IV to be used for the cipher.

This should generally be called after #key= or after #auth_data= (if using AEAD).

Parameters:

  • iv (String) —

    the IV



136
137
138
 
# File 'lib/botan/cipher.rb', line 136

def iv=(iv)
  start(iv)
end

#key=(key) ⇒ Object

Sets the key to be used for the cipher.

This should generally be the first thing called after creating a new cipher instance (or after reset).

Parameters:

  • key (String) —

    the key



125
126
127
128
 
# File 'lib/botan/cipher.rb', line 125

def key=(key)
  key_buf = FFI::MemoryPointer.from_data(key)
  Botan.call_ffi(:botan_cipher_set_key, @ptr, key_buf, key_buf.size)
end

#key_length_max ⇒ Integer

Retrieves the maximum key length for the cipher.

Returns:

  • (Integer) 


82
83
84
 
# File 'lib/botan/cipher.rb', line 82

def key_length_max
  key_lengths[1]
end

#key_length_min ⇒ Integer

Retrieves the minimum key length for the cipher.

Returns:

  • (Integer) 


75
76
77
 
# File 'lib/botan/cipher.rb', line 75

def key_length_min
  key_lengths[0]
end

#reset ⇒ self

Resets the cipher state.

Returns:

  • (self) 


114
115
116
117
 
# File 'lib/botan/cipher.rb', line 114

def reset
  Botan.call_ffi(:botan_cipher_clear, @ptr)
  self
end

#tag_length ⇒ Integer

Retrieves the tag length when using AEAD modes.

Returns:

  • (Integer) 


89
90
91
92
93
 
# File 'lib/botan/cipher.rb', line 89

def tag_length
  length_ptr = FFI::MemoryPointer.new(:size_t)
  Botan.call_ffi(:botan_cipher_get_tag_length, @ptr, length_ptr)
  length_ptr.read(:size_t)
end

#update(data) ⇒ String

Process the data (encrypt/decrypt).

Parameters:

  • data (String) —

    the data to encrypt or decrypt. The size should likely be a multiple of #update_granularity.

Returns:

  • (String) —

    the ciphertext or plaintext



155
156
157
 
# File 'lib/botan/cipher.rb', line 155

def update(data)
  _update(data, final: false)
end

#update_granularity ⇒ Integer

Retrieves the update granularity for the cipher.

Returns:

  • (Integer) 


66
67
68
69
70
 
# File 'lib/botan/cipher.rb', line 66

def update_granularity
  gran_ptr = FFI::MemoryPointer.new(:size_t)
  Botan.call_ffi(:botan_cipher_get_update_granularity, @ptr, gran_ptr)
  gran_ptr.read(:size_t)
end

#valid_nonce_length?(nonce_len) ⇒ Boolean

Checks whether a nonce length is valid for this cipher.

Parameters:

  • nonce_len (Integer) —

    the nonce length to check

Returns:

  • (Boolean) —

    true if the provided nonce length is valid



106
107
108
109
 
# File 'lib/botan/cipher.rb', line 106

def valid_nonce_length?(nonce_len)
  rc = Botan.call_ffi_rc(:botan_cipher_valid_nonce_length, @ptr, nonce_len)
  rc == 1
end