1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00

[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
This commit is contained in:
Kazuki Yamaguchi 2021-11-01 17:23:07 +09:00
parent 1ac7f23bb8
commit b474049c78
2 changed files with 27 additions and 2 deletions

View file

@ -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 (<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

View file

@ -291,7 +291,14 @@ x509name_print(VALUE self, unsigned long iflag)
* * 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)
* 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']]
*/