diff options
Diffstat (limited to 'lib/drb')
| -rw-r--r-- | lib/drb/drb.rb | 57 | ||||
| -rw-r--r-- | lib/drb/ssl.rb | 156 |
2 files changed, 194 insertions, 19 deletions
diff --git a/lib/drb/drb.rb b/lib/drb/drb.rb index f5d4a26906..1d3c413e0c 100644 --- a/lib/drb/drb.rb +++ b/lib/drb/drb.rb @@ -514,8 +514,8 @@ module DRb class DRbArray - # Creates a new DRbArray that either dumps or wraps all the items in +ary+ - # so they can be loaded by a remote DRb server. + # Creates a new DRbArray that either dumps or wraps all the items in the + # Array +ary+ so they can be loaded by a remote DRb server. def initialize(ary) @ary = ary.collect { |obj| @@ -826,7 +826,12 @@ module DRb public - # Open a client connection to +uri+ using configuration +config+. + # Open a client connection to +uri+ (DRb URI string) using configuration + # +config+. + # + # This can raise DRb::DRbBadScheme or DRb::DRbBadURI if +uri+ is not for a + # recognized protocol. See DRb::DRbServer.new for information on built-in + # URI protocols. def self.open(uri, config) host, port, = parse_uri(uri) host.untaint @@ -835,6 +840,7 @@ module DRb self.new(uri, soc, config) end + # Returns the hostname of this server def self.getservername host = Socket::gethostname begin @@ -844,6 +850,9 @@ module DRb end end + # For the families available for +host+, returns a TCPServer on +port+. + # If +port+ is 0 the first available port is used. IPv4 servers are + # preferred over IPv6 servers. def self.open_server_inaddr_any(host, port) infos = Socket::getaddrinfo(host, nil, Socket::AF_UNSPEC, @@ -1023,7 +1032,8 @@ module DRb self.new_with(uri, ref) end - # Creates a new DRbObject from a +uri+ and object +ref+. + # Creates a DRb::DRbObject given the reference information to the remote + # host +uri+ and object +ref+. def self.new_with(uri, ref) it = self.allocate @@ -1112,6 +1122,7 @@ module DRb end end + # Given the +uri+ of another host executes the block provided. def self.with_friend(uri) # :nodoc: friend = DRb.fetch_server(uri) return yield() unless friend @@ -1123,6 +1134,8 @@ module DRb Thread.current['DRb'] = save if friend end + # Returns a modified backtrace from +result+ with the +uri+ where each call + # in the backtrace came from. def self.prepare_backtrace(uri, result) # :nodoc: prefix = "(#{uri}) " bt = [] @@ -1254,9 +1267,9 @@ module DRb @@load_limit = sz end - # Set the default value for the :acl option. + # Set the default access control list to +acl+. The default ACL is +nil+. # - # See #new(). The initial default value is nil. + # See also DRb::ACL and #new() def self.default_acl(acl) @@acl = acl end @@ -1268,7 +1281,9 @@ module DRb @@idconv = idconv end - # Set the default safe level to +level+ + # Set the default safe level to +level+. The default safe level is 0 + # + # See #new for more information. def self.default_safe_level(level) @@safe_level = level end @@ -1326,6 +1341,9 @@ module DRb # :argc_limit :: the maximum number of arguments to a remote # method accepted by the server. Defaults to # 256. + # :safe_level :: The safe level of the DRbServer. The attribute + # sets $SAFE for methods performed in the main_loop. + # Defaults to 0. # # The default values of these options can be modified on # a class-wide basis by the class methods #default_argc_limit, @@ -1385,7 +1403,10 @@ module DRb # The configuration of this DRbServer attr_reader :config - # The safe level for this server + # The safe level for this server. This is a number corresponding to + # $SAFE. + # + # The default safe_level is 0 attr_reader :safe_level # Set whether to operate in verbose mode. @@ -1741,7 +1762,10 @@ module DRb end module_function :thread - # Set the default id conv object. + # Set the default id conversion object. + # + # This is expected to be an instance such as DRb::DRbIdConv that responds to + # #to_id and #to_obj that can convert objects to and from DRb references. # # See DRbServer#default_id_conv. def install_id_conv(idconv) @@ -1749,7 +1773,7 @@ module DRb end module_function :install_id_conv - # Set the default acl. + # Set the default ACL to +acl+. # # See DRb::DRbServer.default_acl. def install_acl(acl) @@ -1766,7 +1790,16 @@ module DRb @server = {} # Registers +server+ with DRb. # + # This is called when a new DRb::DRbServer is created. + # # If there is no primary server then +server+ becomes the primary server. + # + # Example: + # + # require 'drb' + # + # s = DRb::DRbServer.new # automatically calls regist_server + # DRb.fetch_server s.uri #=> #<DRb::DRbServer:0x...> def regist_server(server) @server[server.uri] = server mutex.synchronize do @@ -1775,13 +1808,15 @@ module DRb end module_function :regist_server - # Removes +server+ from the list of servers. + # Removes +server+ from the list of registered servers. def remove_server(server) @server.delete(server.uri) end module_function :remove_server # Retrieves the server with the given +uri+. + # + # See also regist_server and remove_server. def fetch_server(uri) @server[uri] end diff --git a/lib/drb/ssl.rb b/lib/drb/ssl.rb index c0dd9c49f4..8651702797 100644 --- a/lib/drb/ssl.rb +++ b/lib/drb/ssl.rb @@ -11,9 +11,18 @@ module DRb # <code>drbssl://<host>:<port>?<option></code>. The option is optional class DRbSSLSocket < DRbTCPSocket - # :stopdoc: + # SSLConfig handles the needed SSL information for establishing a + # DRbSSLSocket connection, including generating the X509 / RSA pair. + # + # An instance of this config can be passed to DRbSSLSocket.new, + # DRbSSLSocket.open and DRbSSLSocket.open_server + # + # See DRb::DRbSSLSocket::SSLConfig.new for more details class SSLConfig + # Default values for a SSLConfig instance. + # + # See DRb::DRbSSLSocket::SSLConfig.new for more details DEFAULT = { :SSLCertificate => nil, :SSLPrivateKey => nil, @@ -30,6 +39,90 @@ module DRb :SSLCertComment => "Generated by Ruby/OpenSSL" } + # Create a new DRb::DRbSSLSocket::SSLConfig instance + # + # The DRb::DRbSSLSocket will take either a +config+ Hash or an instance + # of SSLConfg, and will setup the certificate for its session for the + # configuration. If want it to generate a generic certificate, the bare + # minimum is to provide the :SSLCertName + # + # === Config options + # + # From +config+ Hash: + # + # :SSLCertificate :: + # An instance of OpenSSL::X509::Certificate. If this is not provided, + # then a generic X509 is generated, with a correspond :SSLPrivateKey + # + # :SSLPrivateKey :: + # A private key instance, like OpenSSL::PKey::RSA. This key must be + # the key that signed the :SSLCertificate + # + # :SSLClientCA :: + # An OpenSSL::X509::Certificate, or Array of certificates that will + # used as ClientCAs in the SSL Context + # + # :SSLCACertificatePath :: + # A path to the directory of CA certificates. The certificates must + # be in PEM format. + # + # :SSLCACertificateFile :: + # A path to a CA certificate file, in PEM format. + # + # :SSLTmpDhCallback :: + # A DH callback. See OpenSSL::SSL::SSLContext.tmp_dh_callback + # + # :SSLVerifyMode :: + # This is the SSL verification mode. See OpenSSL::SSL::VERIFY_* for + # available modes. The default is OpenSSL::SSL::VERIFY_NONE + # + # :SSLVerifyDepth :: + # Number of CA certificates to walk, when verifying a certificate + # chain. + # + # :SSLVerifyCallback :: + # A callback to be used for additional verification. See + # OpenSSL::SSL::SSLContext.verify_callback + # + # :SSLCertificateStore :: + # A OpenSSL::X509::Store used for verification of certificates + # + # :SSLCertName :: + # Issuer name for the certificate. This is required when generating + # the certificate (if :SSLCertificate and :SSLPrivateKey were not + # given). The value of this is to be an Array of pairs: + # + # [["C", "Raleigh"], ["ST","North Carolina"], + # ["CN","fqdn.example.com"]] + # + # See also OpenSSL::X509::Name + # + # :SSLCertComment :: + # A comment to be used for generating the certificate. The default is + # "Generated by Ruby/OpenSSL" + # + # + # === Example + # + # These values can be added after the fact, like a Hash. + # + # require 'drb/ssl' + # c = DRb::DRbSSLSocket::SSLConfig.new {} + # c[:SSLCertificate] = + # OpenSSL::X509::Certificate.new(File.read('mycert.crt')) + # c[:SSLPrivateKey] = OpenSSL::PKey::RSA.new(File.read('mycert.key')) + # c[:SSLVerifyMode] = OpenSSL::SSL::VERIFY_PEER + # c[:SSLCACertificatePath] = "/etc/ssl/certs/" + # c.setup_certificate + # + # or + # + # require 'drb/ssl' + # c = DRb::DRbSSLSocket::SSLConfig.new({ + # :SSLCertName => [["CN" => DRb::DRbSSLSocket.getservername]] + # }) + # c.setup_certificate + # def initialize(config) @config = config @cert = config[:SSLCertificate] @@ -37,10 +130,13 @@ module DRb @ssl_ctx = nil end + # A convenience method to access the values like a Hash def [](key); @config[key] || DEFAULT[key] end + # Connect to IO +tcp+, with context of the current certificate + # configuration def connect(tcp) ssl = ::OpenSSL::SSL::SSLSocket.new(tcp, @ssl_ctx) ssl.sync = true @@ -48,6 +144,8 @@ module DRb ssl end + # Accept connection to IO +tcp+, with context of the current certificate + # configuration def accept(tcp) ssl = OpenSSL::SSL::SSLSocket.new(tcp, @ssl_ctx) ssl.sync = true @@ -55,6 +153,9 @@ module DRb ssl end + # Ensures that :SSLCertificate and :SSLPrivateKey have been provided + # or that a new certificate is generated with the other parameters + # provided. def setup_certificate if @cert && @pkey return @@ -100,6 +201,8 @@ module DRb @pkey = rsa end + # Establish the OpenSSL::SSL::SSLContext with the configuration + # parameters provided. def setup_ssl_context ctx = ::OpenSSL::SSL::SSLContext.new ctx.cert = @cert @@ -116,7 +219,12 @@ module DRb end end - def self.parse_uri(uri) + # Parse the dRuby +uri+ for an SSL connection. + # + # Expects drbssl://... + # + # Raises DRbBadScheme or DRbBadURI if +uri+ is not matching or malformed + def self.parse_uri(uri) # :nodoc: if uri =~ /^drbssl:\/\/(.*?):(\d+)(\?(.*))?$/ host = $1 port = $2.to_i @@ -128,6 +236,15 @@ module DRb end end + # Return an DRb::DRbSSLSocket instance as a client-side connection, + # with the SSL connected. This is called from DRb::start_service or while + # connecting to a remote object: + # + # DRb.start_service 'drbssl://localhost:0', front, config + # + # +uri+ is the URI we are connected to, + # <code>'drbssl://localhost:0'</code> above, +config+ is our + # configuration. Either a Hash or DRb::DRbSSLSocket::SSLConfig def self.open(uri, config) host, port, = parse_uri(uri) host.untaint @@ -139,6 +256,15 @@ module DRb self.new(uri, ssl, ssl_conf, true) end + # Returns a DRb::DRbSSLSocket instance as a server-side connection, with + # the SSL connected. This is called from DRb::start_service or while + # connecting to a remote object: + # + # DRb.start_service 'drbssl://localhost:0', front, config + # + # +uri+ is the URI we are connected to, + # <code>'drbssl://localhost:0'</code> above, +config+ is our + # configuration. Either a Hash or DRb::DRbSSLSocket::SSLConfig def self.open_server(uri, config) uri = 'drbssl://:0' unless uri host, port, = parse_uri(uri) @@ -157,19 +283,35 @@ module DRb self.new(@uri, soc, ssl_conf, false) end - def self.uri_option(uri, config) + # This is a convenience method to parse +uri+ and separate out any + # additional options appended in the +uri+. + # + # Returns an option-less uri and the option => [uri,option] + # + # The +config+ is completely unused, so passing nil is sufficient. + def self.uri_option(uri, config) # :nodoc: host, port, option = parse_uri(uri) return "drbssl://#{host}:#{port}", option end + # Create a DRb::DRbSSLSocket instance. + # + # +uri+ is the URI we are connected to. + # +soc+ is the tcp socket we are bound to. + # +config+ is our configuration. Either a Hash or SSLConfig + # +is_established+ is a boolean of whether +soc+ is currenly established + # + # This is called automatically based on the DRb protocol. def initialize(uri, soc, config, is_established) @ssl = is_established ? soc : nil super(uri, soc.to_io, config) end - def stream; @ssl; end + # Returns the SSL stream + def stream; @ssl; end # :nodoc: - def close + # Closes the SSL stream before closing the dRuby connection. + def close # :nodoc: if @ssl @ssl.close @ssl = nil @@ -177,7 +319,7 @@ module DRb super end - def accept + def accept # :nodoc: begin while true soc = @socket.accept @@ -195,8 +337,6 @@ module DRb retry end end - - # :stopdoc: end DRbProtocol.add_protocol(DRbSSLSocket) |