From 33b63fcf93d2116e9e9aa9b4fd9ef91bcaad9b05 Mon Sep 17 00:00:00 2001 From: zzak Date: Wed, 13 Nov 2013 08:15:48 +0000 Subject: * ext/openssl/lib/openssl/*.rb: [DOC] Document the following: - Integer#to_bn - OpenSSL::Buffering module - Document deprecated OpenSSL::Digest::Digest compatibility class - OpenSSL::Config These changes were based on a patch by @vbatts via GH-436 https://github.com/ruby/ruby/pull/436 git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@43663 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ext/openssl/lib/openssl/bn.rb | 3 + ext/openssl/lib/openssl/buffering.rb | 6 ++ ext/openssl/lib/openssl/config.rb | 165 ++++++++++++++++++++++++++++++++++- ext/openssl/lib/openssl/digest.rb | 9 +- 4 files changed, 178 insertions(+), 5 deletions(-) (limited to 'ext/openssl') diff --git a/ext/openssl/lib/openssl/bn.rb b/ext/openssl/lib/openssl/bn.rb index db722438e4..0e19c20d34 100644 --- a/ext/openssl/lib/openssl/bn.rb +++ b/ext/openssl/lib/openssl/bn.rb @@ -28,6 +28,9 @@ end # OpenSSL # Add double dispatch to Integer # class Integer + # Casts an Integer as an OpenSSL::BN + # + # See `man bn` for more info. def to_bn OpenSSL::BN::new(self) end diff --git a/ext/openssl/lib/openssl/buffering.rb b/ext/openssl/lib/openssl/buffering.rb index e40dfee667..bf69ac0988 100644 --- a/ext/openssl/lib/openssl/buffering.rb +++ b/ext/openssl/lib/openssl/buffering.rb @@ -18,6 +18,9 @@ # OpenSSL IO buffering mix-in module. # # This module allows an OpenSSL::SSL::SSLSocket to behave like an IO. +# +# You typically won't use this module directly, you can see it implemented in +# OpenSSL::SSL::SSLSocket. module OpenSSL::Buffering include Enumerable @@ -34,6 +37,9 @@ module OpenSSL::Buffering BLOCK_SIZE = 1024*16 + ## + # Creates an instance of OpenSSL's buffering IO module. + def initialize(*args) @eof = false @rbuffer = "" diff --git a/ext/openssl/lib/openssl/config.rb b/ext/openssl/lib/openssl/config.rb index 24a54c91ec..9f5c6affac 100644 --- a/ext/openssl/lib/openssl/config.rb +++ b/ext/openssl/lib/openssl/config.rb @@ -13,10 +13,25 @@ require 'stringio' module OpenSSL + ## + # = OpenSSL::Config + # + # Configuration for the openssl library. + # + # Many system's installation of openssl library will depend on your system + # configuration. See the value of OpenSSL::Config::DEFAULT_CONFIG_FILE for + # the location of the file for your host. + # + # See also http://www.openssl.org/docs/apps/config.html class Config include Enumerable class << self + + ## + # Parses a given +str+ as a blob that contains configuration for openssl. + # + # If the source of the IO is a file, then consider using #parse_config. def parse(str) c = new() parse_config(StringIO.new(str)).each do |section, hash| @@ -25,8 +40,14 @@ module OpenSSL c end + ## + # load is an alias to ::new alias load new + ## + # Parses the configuration data read from +io+, see also #parse. + # + # Raises a ConfigError on invalid configuration data. def parse_config(io) begin parse_config_lines(io) @@ -209,6 +230,18 @@ module OpenSSL end end + ## + # Creates an instance of OpenSSL's configuration class. + # + # This can be used in contexts like OpenSSL::X509::ExtensionFactory.config= + # + # If the optional +filename+ parameter is provided, then it is read in and + # parsed via #parse_config. + # + # This can raise IO exceptions based on the access, or availability of the + # file. A ConfigError exception may be raised depending on the validity of + # the data being configured. + # def initialize(filename = nil) @data = {} if filename @@ -220,6 +253,23 @@ module OpenSSL end end + ## + # Gets the value of +key+ from the given +section+ + # + # Given the following configurating file being loaded: + # + # config = OpenSSL::Config.load('foo.cnf') + # #=> # + # puts config.to_s + # #=> [ default ] + # # foo=bar + # + # You can get a specific value from the config if you know the +section+ + # and +key+ like so: + # + # config.get_value('default','foo') + # #=> "bar" + # def get_value(section, key) if section.nil? raise TypeError.new('nil not allowed') @@ -228,7 +278,12 @@ module OpenSSL get_key_string(section, key) end - def value(arg1, arg2 = nil) + ## + # + # *Deprecated* + # + # Use #get_value instead + def value(arg1, arg2 = nil) # :nodoc: warn('Config#value is deprecated; use Config#get_value') if arg2.nil? section, key = 'default', arg1 @@ -240,20 +295,84 @@ module OpenSSL get_key_string(section, key) end + ## + # Set the target +key+ with a given +value+ under a specific +section+. + # + # Given the following configurating file being loaded: + # + # config = OpenSSL::Config.load('foo.cnf') + # #=> # + # puts config.to_s + # #=> [ default ] + # # foo=bar + # + # You can set the value of +foo+ under the +default+ section to a new + # value: + # + # config.add_value('default', 'foo', 'buzz') + # #=> "buzz" + # puts config.to_s + # #=> [ default ] + # # foo=buzz + # def add_value(section, key, value) check_modify (@data[section] ||= {})[key] = value end + ## + # Get a specific +section+ from the current configuration + # + # Given the following configurating file being loaded: + # + # config = OpenSSL::Config.load('foo.cnf') + # #=> # + # puts config.to_s + # #=> [ default ] + # # foo=bar + # + # You can get a hash of the specific section like so: + # + # config['default'] + # #=> {"foo"=>"bar"} + # def [](section) @data[section] || {} end - def section(name) + ## + # Deprecated + # + # Use #[] instead + def section(name) # :nodoc: warn('Config#section is deprecated; use Config#[]') @data[name] || {} end + ## + # Sets a specific +section+ name with a Hash +pairs+ + # + # Given the following configuration being created: + # + # config = OpenSSL::Config.new + # #=> # + # config['default'] = {"foo"=>"bar","baz"=>"buz"} + # #=> {"foo"=>"bar", "baz"=>"buz"} + # puts config.to_s + # #=> [ default ] + # # foo=bar + # # baz=buz + # + # It's important to note that this will essentially merge any of the keys + # in +pairs+ with the existing +section+. For example: + # + # config['default'] + # #=> {"foo"=>"bar", "baz"=>"buz"} + # config['default'] = {"foo" => "changed"} + # #=> {"foo"=>"changed"} + # config['default'] + # #=> {"foo"=>"changed", "baz"=>"buz"} + # def []=(section, pairs) check_modify @data[section] ||= {} @@ -262,10 +381,38 @@ module OpenSSL end end + ## + # Get the names of all sections in the current configuration def sections @data.keys end + ## + # Get the parsable form of the current configuration + # + # Given the following configuration being created: + # + # config = OpenSSL::Config.new + # #=> # + # config['default'] = {"foo"=>"bar","baz"=>"buz"} + # #=> {"foo"=>"bar", "baz"=>"buz"} + # puts config.to_s + # #=> [ default ] + # # foo=bar + # # baz=buz + # + # You can parse get the serialized configuration using #to_s and then parse + # it later: + # + # serialized_config = config.to_s + # # much later... + # new_config = OpenSSL::Config.parse(serialized_config) + # #=> # + # puts new_config + # #=> [ default ] + # foo=bar + # baz=buz + # def to_s ary = [] @data.keys.sort.each do |section| @@ -278,6 +425,15 @@ module OpenSSL ary.join end + ## + # For a block. + # + # Receive the section and its pairs for the current configuration. + # + # config.each do |section, key, value| + # # ... + # end + # def each @data.each do |section, hash| hash.each do |key, value| @@ -286,13 +442,16 @@ module OpenSSL end end + ## + # String representation of this configuration object, including the class + # name and its sections. def inspect "#<#{self.class.name} sections=#{sections.inspect}>" end protected - def data + def data # :nodoc: @data end diff --git a/ext/openssl/lib/openssl/digest.rb b/ext/openssl/lib/openssl/digest.rb index f2a47bfdf9..80b58af5da 100644 --- a/ext/openssl/lib/openssl/digest.rb +++ b/ext/openssl/lib/openssl/digest.rb @@ -59,8 +59,13 @@ module OpenSSL const_set(name, klass) } - # This class is only provided for backwards compatibility. Use OpenSSL::Digest in the future. - class Digest < Digest + # This class is only provided for backwards compatibility. + # + # Use OpenSSL::Digest in the future. + class Digest < Digest # :nodoc: + # Deprecated. + # + # See OpenSSL::Digest.new def initialize(*args) # add warning super(*args) -- cgit v1.2.3