krypt 0.0.1

data/lib/krypt/codec.rb

@@ -0,0 +1,57 @@
+module Krypt
+  
+  # Abstract class that represents filters that can be combined with ordinary
+  # IO instances, filtering the output before reading/writing to the underlying
+  # IO. IOFilter instances can be stacked on top of each other, forming a 
+  # "filter chain" that "peels of" multiple layers of encoding for example. 
+  #
+  # IOFilter supports a basic IO interface that responds to IO#read, IO#write
+  # and IO#close.
+  #
+  # When reading from the IOFilter, the data will first be read from the IO,
+  # processed according to the rules of the filter and only then passed on.
+  #
+  # When writing to the IOFilter, the data will first be processed by
+  # applying the filter and only then written to the IO instance.
+  #
+  # Closing the IOFilter with IOFilter#close guarantees (among possibly
+  # additional things) a call to IO#close on the underlying IO.
+  class IOFilter
+    
+    #
+    # call-seq: 
+    #    IOFilter.new(io) [{ |filter| block }] -> IOFilter
+    #
+    # Constructs a new IOFilter with +io+ as its underlying IO. 
+    # Takes an optional block which is yielded the IOFilter +filter+.
+    # After execution of the block, it is guaranteed that IOFilter#close
+    # gets called on the IOFilter.
+    #
+    def initialize(io)
+      @io = io
+      if block_given?
+        begin
+          yield self
+        ensure
+          close
+        end
+      end
+    end
+
+    #
+    # call-seq:
+    #    io.close -> nil
+    #
+    # Calls, among possibly additional cleanup, IO#close on the underlying
+    # IO.
+    def close
+      @io.close
+    end
+  end
+
+  
+end
+
+require_relative 'codec/hex'
+require_relative 'codec/base64'
+

data/lib/krypt/codec/base64.rb

@@ -0,0 +1,140 @@
+require_relative 'base_codec'
+
+module Krypt::Base64
+
+  module Base64Impl #:nodoc:
+    include Krypt::BaseCodec
+
+    def compute_len(len, a, b)
+      len -= @buf.size if @buf
+      ret = a * len / b
+      remainder = ret % a
+      if remainder
+        ret += a - remainder
+      end
+      ret
+    end
+
+    def compute_encode_read_len(len)
+      compute_len(len, 3, 4)
+    end
+
+    def compute_decode_read_len(len)
+      compute_len(len, 4, 3)
+    end
+
+    def generic_close
+      if @write
+        @io.write(Krypt::Base64.encode(@buf)) if @buf
+      else
+        raise Krypt::Base64::Base64Error.new("Remaining bytes in buffer") if @buf
+      end
+    end
+  end
+
+  private_constant :Base64Impl
+
+  # Base64-encodes any data written or read from it in the process.
+  #
+  # === Example: Base64-encode data and write it to a file
+  #
+  #  f = File.open("b64", "wb")
+  #  b64 = Krypt::Base64::Encoder.new(f)
+  #  b64 << "one"
+  #  b64 << "two"
+  #  b64.close # => contents in file will be encoded
+  #
+  # === Example: Reading from a file and Base64-encoding the data
+  #
+  #  f = File.open("document", "rb")
+  #  b64 = Krypt::Base64::Encoder.new(f)
+  #  b64data = b64.read # => result is encoded
+  #  b64.close
+  #
+  class Encoder < Krypt::IOFilter
+    include Base64Impl
+
+    #
+    # call-seq:
+    #    in.read([len=nil]) -> String or nil
+    #
+    # Reads from the underlying IO and Base64-encodes the data.
+    # Please see IO#read for details. Note that in-place reading into
+    # a buffer is not supported.
+    #
+    def read(len=nil)
+      read_len = len ? compute_encode_read_len(len) : nil
+      generic_read(len, read_len) { |data| Krypt::Base64.encode(data) }
+    end
+
+    #
+    # call-seq:
+    #    out.write(string) -> Integer
+    #
+    # Base64-encodes +string+ and writes it to the underlying IO.
+    # Please see IO#write for further details.
+    #
+    def write(data)
+      generic_write(data, 3) { |data| Krypt::Base64.encode(data) }
+    end
+    alias << write
+
+    def close
+      generic_close
+      super
+    end
+
+  end
+  
+  # Base64-decodes any data written or read from it in the process.
+  #
+  # === Example: Reading and decoding Base64-encoded data from a file
+  #
+  #  f = File.open("b64", "rb")
+  #  b64 = Krypt::Base64::Decoder.new(f)
+  #  plain = b64.read # => result is decoded
+  #  b64.close
+  #
+  # === Example: Writing to a file while Base64-decoding the data
+  #
+  #  f = File.open("document", "wb")
+  #  b64 = Krypt::Base64::Decoder.new(f)
+  #  b64data = ... #some Base64-encoded data
+  #  b64 << b64data
+  #  b64.close # => contents in file will be decoded
+  #
+  class Decoder < Krypt::IOFilter
+    include Base64Impl
+
+    #
+    # call-seq:
+    #    in.read([len=nil]) -> String or nil
+    #
+    # Reads from the underlying IO and Base64-decodes the data.
+    # Please see IO#read for further details. Note that in-place reading into
+    # a buffer is not supported.
+    #
+    def read(len=nil)
+      read_len = len ? compute_decode_read_len(len) : nil
+      generic_read(len, read_len) { |data| Krypt::Base64.decode(data) }
+    end
+
+    #
+    # call-seq:
+    #    out.write(string) -> Integer 
+    #
+    # Base64-decodes string and writes it to the underlying IO.
+    # Please see IO#write for further details.
+    #
+    def write(data)
+      generic_write(data, 4) { |data| Krypt::Base64.decode(data) }
+    end
+    alias << write
+
+    def close
+      generic_close
+      super
+    end
+  end
+  
+end

data/lib/krypt/codec/base_codec.rb

@@ -0,0 +1,36 @@
+module Krypt::BaseCodec #:nodoc:
+    
+  def generic_read(len, read_len)
+    data = @io.read(read_len)
+    data = yield data if data
+    if @buf
+      data = data || ""
+      data = @buf << data
+    end
+    return data unless len && data
+    dlen = data.size
+    remainder = dlen - len
+    update_buffer(data, dlen, remainder)
+    data
+  end
+
+  def generic_write(data, blk_size)
+    return 0 unless data
+    @write = true
+    data = @buf ? @buf << data : data.dup
+    dlen = data.size
+    remainder = dlen % blk_size
+    update_buffer(data, dlen, remainder)
+    @io.write(yield data) if data.size > 0
+  end
+
+  def update_buffer(data, dlen, remainder)
+    if remainder > 0
+      @buf = data.slice!(dlen - remainder, remainder)
+    else
+      @buf = nil
+    end
+  end
+
+end
+

data/lib/krypt/codec/hex.rb

@@ -0,0 +1,122 @@
+require_relative 'base_codec'
+
+module Krypt::Hex
+
+  module HexImpl #:nodoc:
+    include Krypt::BaseCodec
+
+    def compute_encode_read_len(len)
+      len
+    end
+
+    def compute_decode_read_len(len)
+      len * 2
+    end
+
+    def generic_close
+      raise Krypt::Hex::HexError.new("Remaining bytes in buffer") if @buf
+    end
+  end
+
+  private_constant :HexImpl
+
+
+  # Hex-encodes any data written or read from it in the process.
+  #
+  # === Example: Hex-encode data and write it to a file
+  #
+  #  f = File.open("hex", "wb")
+  #  hex = Krypt::Hex::Encoder.new(f)
+  #  hex << "one"
+  #  hex << "two"
+  #  hex.close # => contents in file will be encoded
+  #
+  # === Example: Reading from a file and hex-encoding the data
+  #
+  #  f = File.open("document", "rb")
+  #  hex = Krypt::Hex::Encoder.new(f)
+  #  hexdata = hex.read # => result is encoded
+  #  hex.close
+  #
+  class Encoder < Krypt::IOFilter
+    include HexImpl
+
+    #
+    # call-seq:
+    #    in.read([len=nil]) -> String or nil
+    #
+    # Reads from the underlying IO and hex-encodes the data.
+    # Please see IO#read for details. Note that in-place reading into
+    # a buffer is not supported.
+    #
+    def read(len=nil)
+      read_len = len ? compute_encode_read_len(len) : nil
+      generic_read(len, read_len) { |data| Krypt::Hex.encode(data) }
+    end
+
+    #
+    # call-seq:
+    #    out.write(string) -> Integer
+    #
+    # Hex-encodes +string+ and writes it to the underlying IO.
+    # Please see IO#write for further details.
+    #
+    def write(data)
+      generic_write(data, 1) { |data| Krypt::Hex.encode(data) }
+    end
+    alias << write
+
+  end
+  
+  # Hex-decodes any data written or read from it in the process.
+  #
+  # === Example: Reading and decoding hex-encoded data from a file
+  #
+  #  f = File.open("hex", "rb")
+  #  hex = Krypt::Hex::Decoder.new(f)
+  #  plain = hex.read # => result is decoded
+  #  hex.close
+  #
+  # === Example: Writing to a file while hex-decoding the data
+  #
+  #  f = File.open("document", "wb")
+  #  hex = Krypt::Hex::Decoder.new(f)
+  #  hexdata = ... #some hex-encoded data
+  #  hex << hexdata
+  #  hex.close # => contents in file will be decoded
+  #
+  class Decoder < Krypt::IOFilter
+    include HexImpl
+
+    #
+    # call-seq:
+    #    in.read([len=nil], [buf=nil]) -> String or nil
+    #
+    # Reads from the underlying IO and hex-decodes the data.
+    # Please see IO#read for further details. Note that in-place reading into
+    # a buffer is not supported.
+    #
+    def read(len=nil)
+      read_len = len ? compute_decode_read_len(len) : nil
+      generic_read(len, read_len) { |data| Krypt::Hex.decode(data) }
+    end
+
+    #
+    # call-seq:
+    #    out.write(string) -> Integer 
+    #
+    # Hex-decodes string and writes it to the underlying IO.
+    # Please see IO#write for further details.
+    #
+    def write(data)
+      generic_write(data, 2) { |data| Krypt::Hex.decode(data) }
+    end
+    alias << write
+
+    def close
+      generic_close
+      super
+    end
+
+  end
+end

data/lib/krypt/digest.rb

@@ -0,0 +1,112 @@
+##
+# Digest allows you to compute message digests (sometimes
+# interchangeably called "hashes") of arbitrary data that are
+# cryptographically secure, i.e. a Digest implements a secure one-way
+# function.
+#
+# One-way functions offer some useful properties. E.g. given two
+# distinct inputs the probability that both yield the same output
+# is highly unlikely. Combined with the fact that every message digest
+# algorithm has a fixed-length output of just a few bytes, digests are
+# often used to create unique identifiers for arbitrary data. A common
+# example is the creation of a unique id for binary documents that are
+# stored in a database.
+#
+# Another useful characteristic of one-way functions (and thus the name)
+# is that given a digest there is no indication about the original
+# data that produced it, i.e. the only way to identify the original input
+# is to "brute-force" through every possible combination of inputs.
+#
+# These characteristics make one-way functions also ideal companions
+# for public key signature algorithms: instead of signing an entire
+# document, first a hash of the document is produced with a considerably
+# faster message digest algorithm and only the few bytes of its output
+# need to be signed using the slower public key algorithm. To validate
+# the integrity of a signed document, it suffices to re-compute the hash
+# and verify that it is equal to that in the signature.
+#
+# Among the supported message digest algorithms are:
+# * SHA1, SHA224, SHA256, SHA384 and SHA512
+# * MD5
+# * RIPEMD160
+#
+# For each of these algorithms, there is a convenient way to create
+# instances of Digest using them, for example
+#
+#   digest = Krypt::Digest::SHA1.new
+#
+# === Creating Digest by name or by Object Identifier
+#
+# Each supported digest algorithm has an Object Identifier (OID) associated
+# with it. A Digest can either be created by passing the string
+# representation of the corresponding object identifier or by a string
+# representation of the algorithm name.
+#
+# For example, the OBJECT IDENTIFIER for SHA-1 is 1.3.14.3.2.26, so it can
+# be instantiated like this:
+# 
+#   d = Krypt::Digest.new("1.3.14.3.2.26")
+#   d = Krypt::Digest.new("SHA1")
+#   d = Krypt::Digest.new("sha1")
+#
+# Algorithm names may either be all upper- or all lowercase, hyphens are
+# generally stripped: for instance SHA-1 becomes "SHA1", RIPEMD-160 
+# becomes "RIPEMD160".
+#
+# "Breaking" a message digest algorithm means defying its one-way
+# function characteristics, i.e. producing a collision or finding a way
+# to get to the original data by means that are more efficient than
+# brute-forcing etc. Older digest algorithms can be considered broken
+# in this sense, even the very popular MD5 and SHA1 algorithms. Should
+# security be your highest concern, then you should probably rely on
+# SHA224, SHA256, SHA384 or SHA512.
+#
+# === Hashing a file
+#
+#   data = File.read('document')
+#   sha256 = Krypt::Digest::SHA256.new
+#   digest = sha256.digest(data)
+#
+# === Hashing several pieces of data at once
+#
+#   data1 = File.read('file1')
+#   data2 = File.read('file2')
+#   data3 = File.read('file3')
+#   sha256 = Krypt::Digest::SHA256.new
+#   sha256 << data1
+#   sha256 << data2
+#   sha256 << data3
+#   digest = sha256.digest
+#
+# === Reuse a Digest instance
+#
+#   data1 = File.read('file1')
+#   sha256 = Krypt::Digest::SHA256.new
+#   digest1 = sha256.digest(data1)
+#
+#   data2 = File.read('file2')
+#   sha256.reset
+#   digest2 = sha256.digest(data2)
+#
+module Krypt::Digest
+
+  ##
+  # Raised whenever a problem with digests occurs.
+  #
+  class DigestError < Krypt::Error; end
+
+  def self.new(name_or_oid, provider=nil)
+    receiver = provider ? provider : Krypt::Provider
+    f = ->(_) { new_service(Krypt::Digest, name_or_oid) }
+    receiver.instance_eval(&f)
+  end
+
+  %w(SHA1 SHA224 SHA256 SHA384 SHA512 RIPEMD160 MD5).each do |alg|
+    mod = Module.new do
+      define_singleton_method(:new) { Krypt::Digest.new(alg) }
+    end
+    const_set(alg, mod)
+  end
+
+end
+