From b474049c78dc8d6e24aec4c8073240b61b6869f7 Mon Sep 17 00:00:00 2001 From: Kazuki Yamaguchi 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 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'ext/openssl/lib') diff --git a/ext/openssl/lib/openssl/x509.rb b/ext/openssl/lib/openssl/x509.rb index 448941f75e..f973f4f4dc 100644 --- a/ext/openssl/lib/openssl/x509.rb +++ b/ext/openssl/lib/openssl/x509.rb @@ -279,11 +279,29 @@ module OpenSSL 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 (X509_NAME_oneline()) used by + # #to_s. For example: /DC=com/DC=example/CN=nobody + # - \OpenSSL format (X509_NAME_print()) + # used by #to_s(OpenSSL::X509::Name::COMPAT). For example: + # DC=com, DC=example, CN=nobody + # + # 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 -- cgit v1.2.3