botan 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c3e3d7ff23f00256e3b507bdbc67029f88887aa7
+  data.tar.gz: 2eff70990334914d19595cb04907f50256664674
+SHA512:
+  metadata.gz: fd92e2df19b1b3b5092057cd3497774c263c9371caf12dd36df2e8355a20ae1446de63b090570c24d02581d3d9387e2ddedbfc72f85cb18aa905c3ffb01e47eb
+  data.tar.gz: 9280656ff057c834d6fffdd40448aadbcf6492b88121ac364988f44eeb98189035e938fa98c33feab2099d04a4bc6a0bc011897fcaa1f25a30d01cb5d1f8a570

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Ribose Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,219 @@
+# ruby-botan [![codecov.io](https://codecov.io/github/riboseinc/ruby-botan/coverage.svg?branch=master)](https://codecov.io/github/riboseinc/ruby-botan?branch=master)
+
+ruby-botan is a Ruby interface to [Botan](https://botan.randombit.net/).
+
+**Note**: Refer to the Botan documentation in addition to the documentation here. In particular, this note from the Botan manual applies here as well:
+
+> You should have some knowledge of cryptography **before** trying to use the library. This is an area where it is very easy to make mistakes, and where things are often subtle and/or counterintuitive. Obviously the library tries to provide things at a high level precisely to minimize the number of ways things can go wrong, but naive use will almost certainly not result in a secure system.
+
+# Requirements
+
+## Ruby
+
+ruby-botan is currently tested to work with:
+
+* Ruby 2.3
+* Ruby 2.4
+
+## Botan
+
+[Botan](https://botan.randombit.net/) version 2.2 or newer is required.
+
+# Basic Usage
+
+The samples below are meant to be a brief introduction to the library. Refer to the full documentation for full details.
+
+Also see the [examples](https://github.com/riboseinc/ruby-botan/tree/master/examples) directory for examples on using various parts of the library.
+
+## Utilities
+
+```ruby
+Botan.hex_encode("\x01\x02\x03\x04")
+
+Botan.hex_decode('01020304')
+```
+
+## RNG - Random Number Generation
+
+```ruby
+# shortcut method that uses default RNG to get 10 bytes
+Botan::RNG.get(10)
+
+# create a different type of RNG, and reseed from the system RNG
+rng = Botan::RNG.new('user')
+rng.reseed
+rng.get(5)
+```
+
+## Digest / Hash
+
+There are a few different ways to utilize Digest. Which method you choose may depend on whether the data is immediately available in full, or whether it is becoming available over time.
+
+### Simple One-Shot Hash
+
+If you simply want to hash some data that you have immediately available in full, you may want to do something like the following.
+
+```ruby
+Botan::Digest::MD5.digest('my data')
+
+Botan::Digest::SHA256.hexdigest('my data')
+```
+
+You may also use a longer form, in case there is not a pre-defined class (like `MD5` and `SHA256` above). For example:
+
+```ruby
+Botan::Digest.digest('Comb4P(SHA-160,RIPEMD-160)', 'my data')
+
+Botan::Digest.hexdigest('SHA-3(224)', 'my data')
+```
+
+### Continuously Updated Hash
+
+If you have a stream of incoming data that is not readily available that you want to hash, you may proceed in a couple of ways:
+
+```ruby
+# MD5
+md5 = Botan::Digest::MD5.new
+md5.update('my ')
+md5 << 'data'
+md5.hexdigest
+
+# Comb4P hash combiner
+hash = Botan::Digest.new('Comb4P(SHA-160,RIPEMD-160)')
+hash << 'my '
+hash << 'data'
+hash.hexdigest
+```
+
+## Cipher
+
+```ruby
+# encrypt
+enc = Botan::Cipher.encryption('AES-128/CBC/PKCS7')
+key = Botan::RNG.get(enc.key_length_max)
+iv = Botan::RNG.get(enc.default_nonce_length)
+enc.key = key
+enc.iv = iv
+ciphertext = enc.finish('my data')
+
+# decrypt
+dec = Botan::Cipher.decryption('AES-128/CBC/PKCS7')
+dec.key = key
+dec.iv = iv
+plaintext = dec.finish(ciphertext)
+```
+
+## BCrypt
+
+The `Botan::BCrypt` module supports simple bcrypt password hashing.
+
+```ruby
+# generate password hash
+password_input = gets.chomp
+password_hash = Botan::BCrypt.hash(password_input, work_factor: 10)
+
+# check password
+password_input = gets.chomp
+Botan::BCrypt.valid?(password: password_input, phash: password_hash)
+```
+
+## KDF - Key Derivation Functions
+
+The `Botan::KDF` module has a few different functions for key derivation.
+
+```ruby
+Botan::KDF.kdf(algo: 'KDF2(SHA-160)', secret: Botan::RNG.get(9), salt: Botan::RNG.get(7), key_length: 32)
+
+Botan::KDF.pbkdf(algo: 'PBKDF2(CMAC(Blowfish))', password: 'some long passphrase', iterations: 150_000, key_length: 16)
+
+Botan::KDF.pbkdf_timed(algo: 'PBKDF2(SHA-256)', password: 'my secret passphrase', key_length: 8, milliseconds: 100)
+```
+
+## MAC - Message Authentication Code
+
+```ruby
+hmac = Botan::MAC.new('HMAC(SHA-256)')
+hmac.key = Botan.hex_decode('0102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F20')
+hmac << "\x61\x62\x63"
+hmac.hexdigest
+```
+
+## PK - Public Key Cryptography
+
+The `Botan::PK` module exposes functionality for public key loading, exporting, encryption, decryption, signing, and verification.
+
+### Key Generation
+
+```ruby
+# generate a 4096-bit RSA key
+privkey = Botan::PK::PrivateKey.generate('RSA', params: '4096')
+
+# generate an ECDSA key with group secp384r1
+privkey = Botan::PK::PrivateKey.generate('ECDSA', params: 'secp384r1')
+
+# generate a 4096-bit ElGamal key
+privkey = Botan::PK::PrivateKey.generate('ElGamal', params: 'modp/ietf/4096')
+```
+
+### Key Loading
+
+```ruby
+# load a public key
+pubkey = Botan::PK::PublicKey.from_data(File.read('some_file.pem'))
+
+# load an encrypted private key
+privkey = Botan::PK::PrivateKey.from_data(File.read('some_file.pem'), password: 'my key password')
+
+# load an unencrypted private key
+privkey = Botan::PK::PrivateKey.from_data(File.read('some_file.pem'))
+```
+
+### Key Exporting
+
+```ruby
+# private key export (PEM)
+pem = privkey.export_pem(password: 'my secret password')
+
+# public key export (PEM)
+pem = pubkey.export_pem
+```
+
+### Encryption / Decryption
+
+```ruby
+# using defaults
+ciphertext = pubkey.encrypt('my data')
+plaintext = privkey.decrypt(ciphertext)
+```
+
+### Signing / Verifying
+
+```ruby
+data = 'my data'
+
+# using defaults
+signature = privkey.sign(data)
+valid = pubkey.verify(data: data, signature: signature)
+```
+
+## X.509 Certificates
+
+### Certificate Loading
+
+```ruby
+# load from a file
+cert = Botan::X509::Certificate.from_file('my cert.crt')
+
+# load from some data in memory
+cert = Botan::X509::Certificate.from_data(File.read('my cert.crt'))
+```
+
+### Certificate Properties
+
+```ruby
+# fingerprint
+fpr = cert.fingerprint('SHA-256')
+
+# subject's public key
+pubkey = cert.subject_public_key
+```

data/lib/botan.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# (c) 2017 Ribose Inc.
+
+require 'botan/bcrypt'
+require 'botan/cipher'
+require 'botan/defaults'
+require 'botan/error'
+require 'botan/ffi/libbotan'
+require 'botan/digest'
+require 'botan/kdf'
+require 'botan/mac'
+require 'botan/pk/mceies'
+require 'botan/pk/op/decrypt'
+require 'botan/pk/op/encrypt'
+require 'botan/pk/op/keyagreement'
+require 'botan/pk/op/sign'
+require 'botan/pk/op/verify'
+require 'botan/pk/privatekey'
+require 'botan/pk/publickey'
+require 'botan/rng'
+require 'botan/x509/constraints'
+require 'botan/x509/certificate'
+require 'botan/version'
+

data/lib/botan/bcrypt.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# (c) 2017 Ribose Inc.
+
+require 'ffi'
+
+require 'botan/rng'
+require 'botan/utils'
+
+module Botan
+  # bcrypt password hashing
+  #
+  # == Examples
+  # === examples/bcrypt.rb
+  # {include:file:examples/bcrypt.rb}
+  #
+  module BCrypt
+    # Generates a password hash using bcrypt.
+    #
+    # @param password [String] the password to hash
+    # @param work_factor [Integer] the bcrypt work factor
+    # @param rng [Botan::RNG] the RNG to use
+    # @return [String] the generated password hash
+    def self.hash(password, work_factor: 10, rng: Botan::RNG.new)
+      out_len = 64
+      out_buf = FFI::MemoryPointer.new(:uint8, out_len)
+      flags = 0
+      out_len_ptr = FFI::MemoryPointer.new(:size_t)
+      out_len_ptr.write(:size_t, out_len)
+      Botan.call_ffi(:botan_bcrypt_generate,
+                     out_buf, out_len_ptr,
+                     password, rng.ptr, work_factor, flags)
+      result = out_buf.read_bytes(out_len_ptr.read(:size_t))
+      result = result[0...-1] if result[-1] == "\x00"
+      result
+    end
+
+    # Checks a password against a bcrypt hash.
+    #
+    # @param password [String] the password to hash
+    # @param phash [String] the bcrypt hash
+    # @return [Boolean] true if the provided password is correct
+    def self.valid?(password:, phash:)
+      rc = Botan.call_ffi_rc(:botan_bcrypt_is_valid, password, phash)
+      rc.zero?
+    end
+  end # module
+end # module
+

data/lib/botan/cipher.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+# (c) 2017 Ribose Inc.
+
+require 'ffi'
+
+require 'botan/error'
+require 'botan/ffi/libbotan'
+require 'botan/utils'
+
+module Botan
+  # Cipher
+  #
+  # == Examples
+  # === examples/cipher.rb
+  # {include:file:examples/cipher.rb}
+  #
+  class Cipher
+    # Prefer the shortcuts {encryption} and {decryption} instead.
+    #
+    # @param algo [String] the algorithm to use (example: AES-128/CTR-BE)
+    # @param encrypt [Boolean] true if this will be used for encryption,
+    #                          false if it will be used for decryption.
+    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
+
+    # @api private
+    def self.destroy(ptr)
+      LibBotan.botan_cipher_destroy(ptr)
+    end
+
+    # Creates a new cipher instance for encryption.
+    #
+    # @param algo [String] the algorithm to use (example: AES-128/CTR-BE)
+    # @return [Botan::Cipher] the cipher instance
+    def self.encryption(algo)
+      Cipher.new(algo, encrypt: true)
+    end
+
+    # Creates a new cipher instance for decryption.
+    #
+    # @param algo [String] the algorithm to use (example: AES-128/CTR-BE)
+    # @return [Botan::Cipher] the cipher instance
+    def self.decryption(algo)
+      Cipher.new(algo, encrypt: false)
+    end
+
+    # Retrieves the default nonce length for the cipher.
+    #
+    # @return [Integer]
+    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
+
+    # Retrieves the update granularity for the cipher.
+    #
+    # @return [Integer]
+    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
+
+    # Retrieves the minimum key length for the cipher.
+    #
+    # @return [Integer]
+    def key_length_min
+      key_lengths[0]
+    end
+
+    # Retrieves the maximum key length for the cipher.
+    #
+    # @return [Integer]
+    def key_length_max
+      key_lengths[1]
+    end
+
+    # Retrieves the tag length when using AEAD modes.
+    #
+    # @return [Integer]
+    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
+
+    # Determines whether this is an AEAD mode.
+    #
+    # @return [Boolean] true if this is an AEAD mode
+    def authenticated?
+      tag_length.positive?
+    end
+
+    # Checks whether a nonce length is valid for this cipher.
+    #
+    # @param nonce_len [Integer] the nonce length to check
+    # @return [Boolean] true if the provided nonce length is valid
+    def valid_nonce_length?(nonce_len)
+      rc = Botan.call_ffi_rc(:botan_cipher_valid_nonce_length, @ptr, nonce_len)
+      rc == 1
+    end
+
+    # Resets the cipher state.
+    #
+    # @return [self]
+    def reset
+      Botan.call_ffi(:botan_cipher_clear, @ptr)
+      self
+    end
+
+    # 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).
+    #
+    # @param key [String] the key
+    def key=(key)
+      key_buf = FFI::MemoryPointer.from_data(key)
+      Botan.call_ffi(:botan_cipher_set_key, @ptr, key_buf, key_buf.size)
+    end
+
+    # Sets the IV to be used for the cipher.
+    #
+    # This should generally be called after {#key=} or after
+    # {#auth_data=} (if using AEAD).
+    #
+    # @param iv [String] the IV
+    def iv=(iv)
+      start(iv)
+    end
+
+    # Sets the associated data when using AEAD modes.
+    #
+    # This should be called *after* {#key=} and before {#iv=}.
+    #
+    # @param ad [String] the associated data
+    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
+
+    # Process the data (encrypt/decrypt).
+    #
+    # @param data [String] the data to encrypt or decrypt.
+    #   The size should likely be a multiple of {#update_granularity}.
+    # @return [String] the ciphertext or plaintext
+    def update(data)
+      _update(data, final: false)
+    end
+
+    # 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.
+    #
+    # @param data [String] the data, if any
+    # @return [String] the ciphertext or plaintext
+    def finish(data = nil)
+      _update(data, final: true)
+    end
+
+    def inspect
+      Botan.inspect_ptr(self)
+    end
+
+    private
+
+    def start(nonce)
+      nonce_buf = FFI::MemoryPointer.from_data(nonce)
+      Botan.call_ffi(:botan_cipher_start, @ptr, nonce_buf, nonce_buf.size)
+    end
+
+    def key_lengths
+      kmin_ptr = FFI::MemoryPointer.new(:size_t)
+      kmax_ptr = FFI::MemoryPointer.new(:size_t)
+      Botan.call_ffi(:botan_cipher_query_keylen, @ptr, kmin_ptr, kmax_ptr)
+      [kmin_ptr.read(:size_t), kmax_ptr.read(:size_t)]
+    end
+
+    def _update(data, final:)
+      inp = data ? data : ''
+      flags = final ? 1 : 0
+      out_buf_size = inp.bytesize + (final ? tag_length : 0)
+      # FIXME: botan currently lacks a way of determining the size required
+      # here, taking in to account padding mechanism, etc.
+      out_buf_size += 128
+      out_buf = FFI::MemoryPointer.new(:uint8, out_buf_size)
+      out_written_ptr = FFI::MemoryPointer.new(:size_t)
+      input_buf = FFI::MemoryPointer.from_data(inp)
+      inp_consumed_ptr = FFI::MemoryPointer.new(:size_t)
+      Botan.call_ffi(:botan_cipher_update, @ptr, flags, out_buf, out_buf.size,
+                     out_written_ptr, input_buf, input_buf.size,
+                     inp_consumed_ptr)
+      consumed = inp_consumed_ptr.read(:size_t)
+      if consumed != inp.bytesize
+        raise Botan::Error, 'botan_cipher_update did not consume all input' \
+                            " (#{consumed} out of #{inp.bytesize} bytes)"
+      end
+      out_buf.read_bytes(out_written_ptr.read(:size_t))
+    end
+  end # class
+end # module
+