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

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

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

#inspectObject



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_maxInteger

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_minInteger

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

#resetself

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_lengthInteger

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_granularityInteger

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