lib/t2-server/net/parameters.rb
# Copyright (c) 2010-2014 The University of Manchester, UK.
#
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
# * Neither the names of The University of Manchester nor the names of its
# contributors may be used to endorse or promote products derived from this
# software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
#
# Author: Robert Haines
require 'forwardable'
module T2Server
# This is the base class for holding parameters for network connections. It
# delegates most work to the underlying Hash in which options are actually
# stored.
#
# The parameters that can be set are:
# * :ca_file - A file with the correct CA chain to verify the remote server.
# * :ca_path - A directory containing the CA files for server verification.
# * :verify_peer - Use peer verification? (true or false).
# * :client_certificate - File with the client's certificate and private key.
# * :client_password - The password to unlock the client's private key.
# * :ssl_version - The TLS/SSL version to use (:TLSv1, :SSLv23 or :SSLv3).
# * :open_timeout - The number of seconds to wait while opening a connection.
# * :read_timeout - The number of seconds to wait while reading from a connection.
# All others will be ignored. Any parameters not set will return +nil+ when
# queried.
class ConnectionParameters
# :stopdoc:
ALLOWED_PARAMS = [
:ca_file,
:ca_path,
:verify_peer,
:client_certificate,
:client_password,
:ssl_version,
:open_timeout,
:read_timeout
]
# :startdoc:
extend Forwardable
def_delegators :@params, :[], :to_s, :inspect
# Create a new set of connection parameters with no defaults set.
def initialize
@params = {}
end
# :call-seq:
# [param] = value -> value
#
# Set a connection parameter. See the list of allowed parameters in the
# class description.
def []=(param, value)
@params[param] = value if ALLOWED_PARAMS.include?(param)
end
end
# Connection parameters with sensible defaults set for standard connections.
# If the connection is over SSL then the peer will be verified using the
# underlying OS's certificate store.
class DefaultConnectionParameters < ConnectionParameters
# Create connection parameters that are secure by default and verify the
# server that is being connected to.
def initialize
super
self[:verify_peer] = true
end
end
# Connection parameters that specifically turn off peer verification when
# using SSL.
class InsecureSSLConnectionParameters < ConnectionParameters
# Create connection parameters that are insecure by default and do not
# verify the server that is connected to.
def initialize
super
self[:verify_peer] = false
end
end
# Connection parameters that specify the use of SSL version 3.
class SSL3ConnectionParameters < DefaultConnectionParameters
# Create connection parameters that specify the use of SSL version 3.
def initialize
super
self[:ssl_version] = :SSLv3
end
end
# Connection parameters that simplify setting up verification of servers with
# "self-signed" or non-standard certificates.
class CustomCASSLConnectionParameters < DefaultConnectionParameters
# :call-seq:
# new(path) -> CustomCASSLConnectionParameters
#
# _path_ can either be a directory where the required certificate is stored
# or the path to the certificate file itself.
def initialize(path)
super()
case path
when String
self[:ca_path] = path if File.directory? path
self[:ca_file] = path if File.file? path
when File
self[:ca_file] = path.path
when Dir
self[:ca_path] = path.path
end
end
end
# Connection parameters that simplify setting up client authentication to a
# server over SSL.
class ClientAuthSSLConnectionParameters < DefaultConnectionParameters
# :call-seq:
# new(certificate, password = nil) -> ClientAuthSSLConnectionParameters
#
# _certificate_ should point to a file with the client user's certificate
# and private key. The key will be unlocked with _password_ if it is
# encrypted. If _password_ is not specified, but needed, then the
# underlying SSL implementation may ask for it if it can.
def initialize(cert, password = nil)
super()
case cert
when String
self[:client_certificate] = cert
when File
self[:client_certificate] = cert.path
end
self[:client_password] = password
end
end
end