https://git.ruby-lang.org/ruby.git/commit/?id=b474049c78

From b474049c78dc8d6e24aec4c8073240b61b6869f7 Mon Sep 17 00:00:00 2001
From: Kazuki Yamaguchi <k@r...>
Date: Mon, 1 Nov 2021 17:23:07 +0900
Subject: [ruby/openssl] x509name: improve docs for X509::Name

Add docs for X509::Name.parse_openssl and X509::Name.parse_rfc2253,
which are currently undocumented despite being widely used.

Small changes are also made to #to_s and the class description to
recommend using RFC 2253-based methods.

Fixes: https://github.com/ruby/openssl/issues/470

https://github.com/ruby/openssl/commit/74041a35d4
---
 ext/openssl/lib/openssl/x509.rb | 18 ++++++++++++++++++
 ext/openssl/ossl_x509name.c     | 11 +++++++++--
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/ext/openssl/lib/openssl/x509.rb b/ext/openssl/lib/openssl/x509.rb
index 448941f75e3..f973f4f4dc6 100644
--- a/ext/openssl/lib/openssl/x509.rb
+++ b/ext/openssl/lib/openssl/x509.rb
@@ -279,11 +279,29 @@ module OpenSSL https://github.com/ruby/ruby/blob/trunk/ext/openssl/lib/openssl/x509.rb#L279
       end
 
       class << self
+        # Parses the UTF-8 string representation of a distinguished name,
+        # according to RFC 2253.
+        #
+        # See also #to_utf8 for the opposite operation.
         def parse_rfc2253(str, template=OBJECT_TYPE_TEMPLATE)
           ary = OpenSSL::X509::Name::RFC2253DN.scan(str)
           self.new(ary, template)
         end
 
+        # Parses the string representation of a distinguished name. Two
+        # different forms are supported:
+        #
+        # - \OpenSSL format (<tt>X509_NAME_oneline()</tt>) used by
+        #   <tt>#to_s</tt>. For example: <tt>/DC=com/DC=example/CN=nobody</tt>
+        # - \OpenSSL format (<tt>X509_NAME_print()</tt>)
+        #   used by <tt>#to_s(OpenSSL::X509::Name::COMPAT)</tt>. For example:
+        #   <tt>DC=com, DC=example, CN=nobody</tt>
+        #
+        # Neither of them is standardized and has quirks and inconsistencies
+        # in handling of escaped characters or multi-valued RDNs.
+        #
+        # Use of this method is discouraged in new applications. See
+        # Name.parse_rfc2253 and #to_utf8 for the alternative.
         def parse_openssl(str, template=OBJECT_TYPE_TEMPLATE)
           if str.start_with?("/")
             # /A=B/C=D format
diff --git a/ext/openssl/ossl_x509name.c b/ext/openssl/ossl_x509name.c
index 1522c3d897c..13a2b2c030f 100644
--- a/ext/openssl/ossl_x509name.c
+++ b/ext/openssl/ossl_x509name.c
@@ -291,7 +291,14 @@ x509name_print(VALUE self, unsigned long iflag) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509name.c#L291
  * * OpenSSL::X509::Name::MULTILINE
  *
  * If _format_ is omitted, the largely broken and traditional OpenSSL format
- * is used.
+ * (<tt>X509_NAME_oneline()</tt> format) is chosen.
+ *
+ * <b>Use of this method is discouraged.</b> None of the formats other than
+ * OpenSSL::X509::Name::RFC2253 is standardized and may show an inconsistent
+ * behavior through \OpenSSL versions.
+ *
+ * It is recommended to use #to_utf8 instead, which is equivalent to calling
+ * <tt>name.to_s(OpenSSL::X509::Name::RFC2253).force_encoding("UTF-8")</tt>.
  */
 static VALUE
 ossl_x509name_to_s(int argc, VALUE *argv, VALUE self)
@@ -498,7 +505,7 @@ ossl_x509name_to_der(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509name.c#L505
  * You can create a Name by parsing a distinguished name String or by
  * supplying the distinguished name as an Array.
  *
- *   name = OpenSSL::X509::Name.parse '/CN=nobody/DC=example'
+ *   name = OpenSSL::X509::Name.parse_rfc2253 'DC=example,CN=nobody'
  *
  *   name = OpenSSL::X509::Name.new [['CN', 'nobody'], ['DC', 'example']]
  */
-- 
cgit v1.2.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/