libtls 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1566c4cd86920d7e089b2087c3b98f62b5d43217
+  data.tar.gz: 3618c5cc4bcd47205a61664c8b52bbeba6bc91df
+SHA512:
+  metadata.gz: fc0d68830f69516be58bf616d81ab44b6bad1e30c9e6882b96dca089fe8a3bf8d6784e45a501098770fecde8922637a3ba6cac7aee083e4a4f1b573df37da50f
+  data.tar.gz: 74d0efa0af199bb1f938e8ee6a70a69d55915108d82c7a3d638c01750ee9d1fa7edb4c8ed66f9071497575db15d43d69e7fbf31ca842e8d5896661eca9731701

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.yardopts

@@ -0,0 +1,3 @@
+--exclude spec
+--hide-void-return
+--files LICENSE

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in libtls.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2015 Mike Burns <mike@mike-burns.com>
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,279 @@
+# libtls for Ruby
+
+This is a set of libtls bindings for Ruby, plus a nice object-oriented layer
+atop the bindings.
+
+## Installation
+
+This gem depends on the libtls library. Make sure you either run OpenBSD or
+have [libressl-portable] installed.
+
+Once libtls itself is installed, add this line to your application's Gemfile:
+
+```ruby
+gem 'libtls'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install libtls
+
+[libressl-portable]: http://www.libressl.org/releases.html
+
+## Usage
+
+This library provides the API on two levels: the raw C functions, and a nice
+object-oriented layer atop it.
+
+### Raw
+
+The raw functions are as follows; see `tls_init`(3) for more information on what
+they do:
+
+- `LibTLS::Raw.tls_init`
+- `LibTLS::Raw.tls_error`
+- `LibTLS::Raw.tls_config_new`
+- `LibTLS::Raw.tls_config_free`
+- `LibTLS::Raw.tls_config_parse_protocols`
+- `LibTLS::Raw.tls_config_set_ca_file`
+- `LibTLS::Raw.tls_config_set_ca_path`
+- `LibTLS::Raw.tls_config_set_ca_mem`
+- `LibTLS::Raw.tls_config_set_cert_file`
+- `LibTLS::Raw.tls_config_set_cert_mem`
+- `LibTLS::Raw.tls_config_set_ciphers`
+- `LibTLS::Raw.tls_config_set_dheparams`
+- `LibTLS::Raw.tls_config_set_ecdhecurve`
+- `LibTLS::Raw.tls_config_set_key_file`
+- `LibTLS::Raw.tls_config_set_key_mem`
+- `LibTLS::Raw.tls_config_set_protocols`
+- `LibTLS::Raw.tls_config_set_verify_depth`
+- `LibTLS::Raw.tls_config_clear_keys`
+- `LibTLS::Raw.tls_config_insecure_noverifycert`
+- `LibTLS::Raw.tls_config_insecure_noverifyname`
+- `LibTLS::Raw.tls_config_verify`
+- `LibTLS::Raw.tls_load_file`
+- `LibTLS::Raw.tls_client`
+- `LibTLS::Raw.tls_server`
+- `LibTLS::Raw.tls_configure`
+- `LibTLS::Raw.tls_reset`
+- `LibTLS::Raw.tls_close`
+- `LibTLS::Raw.tls_free`
+- `LibTLS::Raw.tls_connect`
+- `LibTLS::Raw.tls_connect_fds`
+- `LibTLS::Raw.tls_connect_servername`
+- `LibTLS::Raw.tls_connect_socket`
+- `LibTLS::Raw.tls_accept_fds`
+- `LibTLS::Raw.tls_accept_socket`
+- `LibTLS::Raw.tls_read`
+- `LibTLS::Raw.tls_write`
+
+Of particular note are those functions which take a pointer (`tls_read`,
+`tls_write`, `tls_accept_socket`, and others). These must have an instance of
+`FFI::MemoryPointer` passed to them:
+
+```ruby
+FFI::MemoryPointer.new(:size_t) do |outlen|
+  FFI::MemoryPointer.new(:uchar, 1024, true) do |buf|
+
+    ret = LibTLS::Raw.tls_read(client, buf, 1024, outlen)
+
+    if ret < 0
+      raise "tls_read: #{LibTLS::Raw.tls_error(client)}"
+    end
+
+  end
+end
+```
+
+Additionally, instance of Ruby's `Socket` object must be converted to their
+file descriptor before interfacing with the C function. The `tls_accept_socket`
+function combines the `FFI::MemoryPointer` requirement with this file
+descriptor requirement:
+
+```ruby
+  cctx_ptr = FFI::MemoryPointer.new(:pointer)
+
+  if tls_accept_socket(server, cctx_ptr, socket.fileno) == -1
+    raise "tls_accept_socket: #{LibTLS::Raw.tls_error(server)}"
+  end
+
+  cctx = cctx_ptr.read_pointer
+```
+
+Constants from `tls.h` are manually re-exposed under the `LibTLS::Raw`
+namespace:
+
+- `LibTLS::Raw::TLS_API`
+- `LibTLS::Raw::TLS_PROTOCOL_TLSv1_0`
+- `LibTLS::Raw::TLS_PROTOCOL_TLSv1_1`
+- `LibTLS::Raw::TLS_PROTOCOL_TLSv1_2`
+- `LibTLS::Raw::TLS_PROTOCOL_TLSv1`
+- `LibTLS::Raw::TLS_PROTOCOLS_ALL`
+- `LibTLS::Raw::TLS_PROTOCOLS_DEFAULT`
+- `LibTLS::Raw::TLS_READ_AGAIN`
+- `LibTLS::Raw::TLS_WRITE_AGAIN`
+
+### Object-Oriented Wrapper
+
+An object-oriented wrapper is provided. Here is an example of a client:
+
+```ruby
+# Get the contents of the Web page hosted at https://#{hostname}:443#{path} .
+def get(hostname, path)
+  # The return value: nil, or a string.
+  content = nil
+
+  # TLS configuration. The key is formed from the series of tls_config_set_*
+  # functions; the value is either the scalar value (int or string), or an
+  # array of the multiple values. For example, ca_mem takes an array with the
+  # FFI::MemoryPointer and the length of that pointer.
+  config = {
+    ciphers: "DES-CBC3-SHA",
+    protocols: LibTLS::Raw::TLS_PROTOCOLS_ALL
+  }
+
+  # Create a new libtls client. The block is then immediately run, and then the
+  # memory free'd.
+  LibTLS::Client.new(configure: config) do |client|
+    # Connect to the server on port 443. When the block finishes, disconnect.
+    content = client.connect("mike-burns.com", 443) do |c|
+      # Send a string to the server; in this case, a HTTP request.
+      c.write(http_get(hostname, path))
+      # Read all the data from the server, and return it. The return value of
+      # this block is the return value of Client#connect.
+      c.read
+    end
+  end
+
+  # Return the content.
+  content
+end
+
+# Generate a HTTP request string.
+def http_get(hostname, path)
+  ["GET #{path} HTTP/1.1",
+   "User-Agent: libtls.rb/0.1",
+   "Host: #{hostname}"].join("\r\n") +
+   "\r\n"
+end
+```
+
+And here is an example of a simple echo server:
+
+```ruby
+# Reply to the socket's clients with their own string.
+def echo_server(socket)
+  # Encrypt communications using the key and cert as generated by e.g.
+  # LibreSSL.
+  config = {
+      key_file: "thekey.key",
+      cert_file: "thecert.crt"
+  }
+
+  # Create and configure a new server object. The block is then immediately
+  # run, and then the memory is free'd.
+  LibTLS::Server.new(configure: config) do |server|
+    # Block until a client connects on client_socket.
+    client_socket, _ = socket.accept
+
+    # Loop forever; this allows another client to connect after this one.
+    loop do
+      # Handle the TLS handshake on the client socket. This takes a block,
+      # which is run immediately after the handshake has completed
+      # successfully. After the block finishes, disconnect and clean up. The
+      # block takes an opened client object.
+      server.accept(client_socket) do |c|
+        # Loop so that the client can write until they disconnect.
+        loop do
+          # Read the entirety of the client's string.
+          str = c.read
+          # Write exactly what the client sent.
+          c.write(str)
+        end
+      end
+    end
+  end
+end
+```
+
+The underlying `struct tls *` object is exposed through the `#ctx` method; it
+can be passed to any `LibTLS::Raw` method, for example.
+
+These methods can raise instances of `LibTLS::UnknownCError` and
+`LibTLS::CError`. Instances of the first are raised when we do not have access
+to the underlying issue, and instances of the second attempt to include the
+error string from libtls.
+
+## Contributing
+
+As contributors and maintainers of this project, we will respect all people
+who contribute in any fashion. We are committed to making participation in this
+project a harassment-free experience for everyone, regardless of who they are.
+
+The project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this code of conduct. Project maintainers who do not
+follow the code of conduct may be removed from the project team.
+
+Instances of unacceptable behavior may be reported by [opening an
+issue][issues] or contacting [Mike Burns](mailto:mike@mike-burns.com)
+([PGP key][Mike PGP key]).
+
+[issues]: https://github.com/mike-burns/libtls.rb/issues
+[Mike PGP key]: http://pgp.mit.edu/pks/lookup?op=get&search=0x3E6761F72846B014
+
+### To contribute a feature
+
+1. Fork it ( https://github.com/mike-burns/libtls.rb/fork )
+2. Make sure the tests pass (`rake`)
+3. Create your feature branch (`git checkout -b my-new-feature`)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Make sure the tests pass (`rake`)
+7. Make sure documentation is complete (`yard`)
+8. Create a new Pull Request
+
+*Feature requests without patches will be closed*.
+
+### To report a security issue
+
+If the issue should be kept quiet for security reasons, email
+[Mike Burns](mailto:mike@mike-burns.com) directly. His PGP key id is
+[0x2846b014][Mike PGP key], fingerprint:
+
+    5FD8 2CE6 A646 3285 538F
+    C3A5 3E67 61F7 2846 B014
+
+## Credits
+
+libtls for Ruby is by [Mike Burns]. It is released under the
+[ISC license][LICENSE].
+
+It would have been impossible to make this library so quickly without the
+knowledge gained on [erltls] with [Rebecca Meritz].
+
+GNU help was provided by [Matt Horan].
+
+The [ffi] gem has also proven crucial to this project; thanks to
+[Wayne Meissner, et al.][ffi credits], for their amazing work on that.
+
+The code of conduct is adapted from the [Contributor Covenant],
+[version 1.1.0][coc110].
+
+[Donate to the OpenBSD Foundation][donate]. Without them, none of this would
+exist.
+
+[Mike Burns]: https://mike-burns.com
+[Rebecca Meritz]: http://rebecca.meritz.com/
+[Matt Horan]: https://matthoran.com/
+[LICENSE]: LICENSE
+[donate]: http://www.openbsdfoundation.org/donations.html
+[ffi]: https://github.com/ffi/ffi/wiki
+[ffi credits]: https://github.com/ffi/ffi/#credits
+[erltls]: https://github.com/meritz-burns/erltls
+[Contributor Covenant]: http://contributor-covenant.org
+[coc110]: http://contributor-covenant.org/version/1/1/0/

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+
+  task default: :spec
+rescue LoadError
+end

data/lib/libtls.rb

@@ -0,0 +1,9 @@
+require 'libtls/version'
+require 'libtls/raw'
+require 'libtls/client'
+require 'libtls/server'
+
+##
+# {include:file:README.md}
+module LibTLS
+end

data/lib/libtls/client.rb

@@ -0,0 +1,195 @@
+require 'libtls/config'
+require 'libtls/raw'
+
+module LibTLS
+##
+# This class represents a TLS client connecting to a server. Here is a sample
+# HTTPS session; this #get method will produce the content at the specified
+# path on the hostname:
+#
+#   def get(hostname, path)
+#     content = nil
+#     config = { ca_file: '/etc/ssl/cert.pem' }
+#   
+#     LibTLS::Client.new(configure: config) do |client|
+#       content = client.connect("mike-burns.com", 443) do |c|
+#         c.write(http_get(hostname, path))
+#         c.read
+#       end
+#     end
+#   
+#     content
+#   end
+#   
+#   def http_get(hostname, path)
+#     ["GET #{path} HTTP/1.1",
+#      "User-Agent: libtls.rb/0.1",
+#      "Host: #{hostname}"].join("\r\n") +
+#      "\r\n"
+#   end
+class Client
+  ##
+  # The FFI wrapper around the struct tls object
+  #
+  # This is only useful for calling any of the {LibTLS::Raw} methods.
+  attr_reader :ctx
+
+  ##
+  # Construct a new [Client] instance
+  #
+  # Once constructed, it runs the block. When the block finishes, it calls
+  # {#finish}.
+  #
+  # @param configure [Hash] a mapping from setting name to value. The setting
+  #   name is any of {LibTLS::Config::VALID_SET_CONFIGS}; the value is either a
+  #   scalar value passed through to the C function, or an array of values. For
+  #   example:
+  #     { ca_file: 'ca.pem', key_mem: [key_ptr, 48] }
+  # @yieldparam [Client] self an initialized and configured instance of self
+  # @raise [LibTLS::UnknownCError] if +tls_init+ or +tls_client+ fails
+  # @raise [LibTLS::CError] if +tls_configure+ fails
+  def initialize(configure:, &block)
+    if LibTLS::Raw.tls_init < 0
+      raise LibTLS::UnknownCError, "tls_init"
+    end
+
+    @config = Config.new(configure)
+
+    if (@ctx = LibTLS::Raw.tls_client).null?
+      raise LibTLS::UnknownCError, "tls_client"
+    end
+
+    if LibTLS::Raw::tls_configure(ctx, @config.as_raw) < 0
+      raise LibTLS::CError, "tls_configure: #{LibTLS::Raw.tls_error(ctx)}"
+    end
+
+    if block
+      begin
+        block.call(self)
+      ensure
+        self.finish
+      end
+    end
+  end
+
+  ##
+  # Open a connection with the server
+  #
+  # This method negotiates the TLS connection with the +hostname+, at the
+  # +port+. Once connected, it passes the connected client to the block. Once
+  # the block finishes, it calls {OpenedClient#close} on the connection.
+  #
+  # @param hostname [String] the server to connect to, as an IPv4 address, an
+  #   IPv6 address, or anything that can be resolved by +getaddrinfo+.
+  # @param port [#to_s] the port on the server to connect to
+  # @yieldparam [OpenedClient] client a connected client
+  # @raise [LibTLS::CError] if the +tls_connect+ fails
+  # @return the result of the block
+  def connect(hostname, port, &block)
+    opened_client = nil
+
+    begin
+      if LibTLS::Raw.tls_connect(ctx, hostname, port.to_s) < 0
+        raise LibTLS::CError, "tls_connect: #{LibTLS::Raw.tls_error(ctx)}"
+      end
+
+      opened_client = OpenedClient.new(ctx)
+      block.call(opened_client)
+    ensure
+      opened_client && opened_client.close
+    end
+  end
+
+  ##
+  # Release any memory held on to by the C library
+  #
+  # This method must be called either implicitly by passing a block to
+  # {#initialize}, or explicitly by you.
+  def finish
+    @config.free
+    LibTLS::Raw.tls_free(ctx)
+  end
+end
+
+private
+
+##
+# A TLS client connected to a server
+#
+# This class must be instantiated only by {LibTLS::Client#connect} and
+# {LibTLS::Server#accept}.
+#
+# When finished, {#close} must be called. This is implicitly handled for you by
+# passing a block to the methods mentioned above.
+class OpenedClient
+  READ_LEN = 1024
+  private_constant :READ_LEN
+
+  ##
+  # The FFI wrapper around the struct tls object
+  #
+  # This is only useful for calling any of the {LibTLS::Raw} methods.
+  attr_reader :ctx
+
+  ##
+  # @api private
+  def initialize(ctx)
+    @ctx = ctx
+  end
+
+  ##
+  # Close this connection
+  #
+  # This method must be called either implicitly by passing a block to
+  # {LibTLS::Client#connect} or {LibTLS::Server#accept}, or explicitly by you.
+  def close
+    if LibTLS::Raw.tls_close(ctx) < 0
+      raise LibTLS::CError, "tls_close: #{LibTLS::Raw.tls_error(ctx)}"
+    end
+  end
+
+  ##
+  # Write the string to the connection
+  #
+  # @param [String] str the string to write
+  # @raise [LibTLS::CError] if +tls_write+ fails
+  def write(str)
+    FFI::MemoryPointer.new(:size_t) do |outlen|
+      FFI::MemoryPointer.new(:uchar, str.length + 1) do |str_ptr|
+        str_ptr.put_string(0, str)
+
+        if LibTLS::Raw.tls_write(ctx, str_ptr, str.length, outlen) < 0
+          raise LibTLS::CError, "tls_write: #{LibTLS::Raw.tls_error(ctx)}"
+        end
+      end
+    end
+  end
+
+  ##
+  # Read a string from the connection
+  #
+  # @raise [LibTLS::CError] if +tls_read+ fails
+  # @return [String] the accumulated buffer
+  def read
+    str = ""
+
+    FFI::MemoryPointer.new(:size_t) do |outlen|
+      FFI::MemoryPointer.new(:uchar, READ_LEN, true) do |buf|
+        loop do
+          if LibTLS::Raw.tls_read(ctx, buf, READ_LEN, outlen) < 0
+            raise LibTLS::CError, "tls_read: #{LibTLS::Raw.tls_error(ctx)}"
+          end
+
+          str += buf.get_string(0, outlen.get_int(0))
+
+          if READ_LEN > outlen.get_int(0)
+            break
+          end
+        end
+      end
+    end
+
+    str
+  end
+end
+end