class Ronin::Support::Crypto::Cipher

Represents a cryptographic cipher.

## Examples

### Encrypt Data

aes256 = Crypto::Cipher.new('aes-256-cbc', direction: :encrypt,
                                           password: 'secret')
aes256.encrypt("message in a bottle")
# => "\x18\xC7\x00~\xA2\xA1\x80\x84c\x98,81mo\xBAZ\xDD\xF4\xF2\xEF\xA9\xDE\xB3\xD6!\xB9\xA8WT\x9D\xE0"

### Decrypt Data

aes256 = Crypto::Cipher.new('aes-256-cbc', direction: :decrypt,
                                           password: 'secret')
aes256.decrypt("\x18\xC7\x00~\xA2\xA1\x80\x84c\x98,81mo\xBAZ\xDD\xF4\xF2\xEF\xA9\xDE\xB3\xD6!\xB9\xA8WT\x9D\xE0")
# => "message in a bottle"

@see rubydoc.info/stdlib/openssl/OpenSSL/Cipher.html

@since 1.0.0

@api public

Public Class Methods

new(name, direction: , key: nil, hash: :sha256, password: nil, iv: nil, padding: nil) click to toggle source

Initializes the cipher.

@param [String] name

The name of the cipher.

@param [:encrypt, :decrypt] direction

Specifies whether the cipher will be used to encrypt or decrypt
data.

@param [Symbol, nil] hash

The algorithm to hash the `:password`.

@param [String, nil] key

The secret key to use.

@param [String, nil] password

The password for the cipher.

@param [String, nil] iv

The optional Initial Vector (IV).

@param [Integer, nil] padding

Sets the padding for the cipher.

@raise [ArgumentError]

The `key:` or `password:` keyword arguments were not given.
Calls superclass method
# File lib/ronin/support/crypto/cipher.rb, line 79
def initialize(name, direction: ,
                     key:       nil,
                     hash:      :sha256,
                     password:  nil,
                     iv:        nil,
                     padding:   nil)
  super(name)

  case direction
  when :encrypt then self.encrypt
  when :decrypt then self.decrypt
  end

  if password && hash
    self.key = OpenSSL::Digest.const_get(hash.upcase).digest(password)
  elsif key
    self.key = key
  else
    raise(ArgumentError,"the the key: or password: keyword argument must be given")
  end

  self.iv      = iv      if iv
  self.padding = padding if padding
end
supported() click to toggle source

The list of supported ciphers.

@return [Array<String>]

The list of supported cipher names.
# File lib/ronin/support/crypto/cipher.rb, line 110
def self.supported
  ciphers
end

Public Instance Methods

decrypt(data=nil) click to toggle source

Decrypts the given data.

@param [String] data

The data to decrypt.

@return [String]

The decrypted data.
Calls superclass method
# File lib/ronin/support/crypto/cipher.rb, line 140
def decrypt(data=nil)
  if data
    update(data) + final
  else
    super()
  end
end
encrypt(data=nil) click to toggle source

Encrypts the given data.

@param [String] data

The data to encrypt.

@return [String]

The encrypted data.
Calls superclass method
# File lib/ronin/support/crypto/cipher.rb, line 123
def encrypt(data=nil)
  if data
    update(data) + final
  else
    super()
  end
end
stream(io, block_size: 16384, output: nil) { |block| ... } click to toggle source

Pipes the IO stream through the cipher.

@param [IO] io

The IO stream to encrypt or decrypt.

@param [Integer] block_size

The block size to read the data with.

@param [String, <<, nil] output

The optional output buffer to append processed data to.
Defaults to an empty ASCII 8bit encoded String.

@yield [block]

If a block is given, each processed block will be passed to it.

@yieldparam [String] block

A processed block from the file.

@return [String]

The processed data, if no block was given.
# File lib/ronin/support/crypto/cipher.rb, line 170
def stream(io, block_size: 16384, output: nil)
  unless block_given?
    output ||= String.new(encoding: Encoding::ASCII_8BIT)
  end

  until io.eof?
    block = update(io.read(block_size))

    if block_given? then yield block
    else                 output << block
    end
  end

  if block_given?
    yield final
  else
    output << final
    return output
  end
end