(#15561) Extract CN from certificate subjects more carefully

When using certificate chaning or otherwise generating SSL certificates
outside of Puppet, the subject often has multiple components, e.g.,
  CN=hostname.foo.com,O=Foo\, Inc.,OU=Marketing
The hostname, which is later verified against a strict set of allowed
characters, is only extracted from the "CN" field, with all of the other
fields ignored.

This uses OpenSSL::X509::Name to parse the DN's, allowing both
rfc2253-formatted and openssl-formatted DNS, as seen from Apache and
nginx, respectively.
(#15561) Make implementation match spec examples

Without this patch applied, the following spec failure occurs.

    3) Puppet::Util::SSL when getting a CN from a subject should return nil for a bare string
       Failure/Error: described_class.cn_from_subject("/CN=foo").should == nil
       NoMethodError:
         undefined method `to_a' for "/CN=foo":String
       # ./lib/puppet/util/ssl.rb:23:in `cn_from_subject'
       # ./spec/unit/util/ssl_spec.rb:47:in `block (3 levels) in <top (required)>'

This failure is caused by the implementation of the `cn_from_subject` method
calling `to_a` on the string, which raises an exception.

This patch makes the implementation match the specified behavior by checking
for the `to_a` method.  If false, `nil` is returned as expected.
(#15561) Doc only YARD cleanup change
(#15561) Fix spec failure in certificate_request_spec

Without this patch applied, the x.509 CN extraction improvements cause
the following spec failure in the certificate_request_spec.rb file

      1) Puppet::SSL::CertificateRequest when converting from a string should create a CSR ...
         Failure/Error: described_class.from_s("my csr")
         NoMethodError:
           undefined method `to_a' for "/CN=Foo.madstop.com":String
         # ./lib/puppet/util/ssl.rb:23:in `cn_from_subject'
         # ./lib/puppet/ssl/base.rb:54:in `name_from_subject'
         # ./lib/puppet/ssl/base.rb:62:in `from_instance'
         # ./lib/puppet/ssl/base.rb:71:in `from_s'
         # ./spec/unit/ssl/certificate_request_spec.rb:42:in `block (3 levels) in <top (required)>'

Poor stubbing is the root cause of this problem.  The mock certificate
object returns a String from `#subject`, however the system expects a
kind of `OpenSSL::X509::Name`.

This patch addresses the problem by changing the mock object to return
an instance of `OpenSSL::X509::Name` when the mocked `#subject` instance
is called.
(#15561) Merge branch 'djmitche-bug15561-subject-fix'

* djmitche-bug15561-subject-fix:
  (#15561) Fix spec failure in certificate_request_spec
  (#15561) Doc only YARD cleanup change
  (#15561) Make implementation match spec examples
  (#15561) Extract CN from certificate subjects more carefully

closes #1556