Backport #7551

Incorrect suggested usage in OpenSSL::X509::ExtensionFactory documentation

Added by Richard Bradley over 1 year ago. Updated about 1 year ago.

[ruby-core:50830]
Status:Closed
Priority:Normal
Assignee:Tomoyuki Chikanaga

Description

The OpenSSL::X509::ExtensionFactory class doesn't have any documentation of its own:
- http://www.ruby-doc.org/stdlib-1.9.3/libdoc/openssl/rdoc/OpenSSL/X509/ExtensionFactory.html
Its usage is shown in a few examples on the OpenSSL lib homepage:
- http://www.ruby-doc.org/stdlib-1.9.3/libdoc/openssl/rdoc/OpenSSL.html
.. however several of these examples are wrong.

The examples show calling "extensionfactory.createextension" and not saving the return value.
If you do not pass the returned value to "cert.add_extension", then the requested extension value will not be added to the certificate.
The attached patch fixes this problem.

The examples on the Certificate documentation are already correct:
- http://ruby-doc.org/stdlib-1.9.3/libdoc/openssl/rdoc/OpenSSL/X509/Certificate.html

Aside about further documentation:

I would be happy to add a bit of documentation to the Ruby OpenSSL lib, but:
1. I would like to add cites to the underlying OpenSSL lib, but that appears to me to be sparsely documented, if at all (for example, the "see objects.h" cite I added in the attached patch is literally the best documentation I could find for the underlying implementation)
2. It's not clear to me which .c comments in which files will get compiled into the rubydoc
.. so perhaps someone else would be better placed to add this documentation. (Although given how long the Ruby OpenSSL lib has existed in its current woefully underdocumented state, perhaps no-one else will?)

If anyone has any suggestions for how I can fix 1 / 2 above, I would be happy to submit further documentation patches.
For now, this is all I have :-)

(If the attached patch is in the wrong format, sorry. Please let me know if so, and what format you prefer, and I can resubmit.)

fix-etension-factory-docs.diff Magnifier (4.24 KB) Richard Bradley, 12/13/2012 01:04 AM

fix-etension-factory-docs.diff Magnifier - Patch v2 (fix some missing brackets) (4.24 KB) Richard Bradley, 12/13/2012 01:06 AM

Associated revisions

Revision 39584
Added by Tomoyuki Chikanaga about 1 year ago

merge revision(s) 39309,39310: [Backport #7551]

* ext/openssl/ossl.c (class OpenSSL):  Fixed ExtensionFactory example.
  Patch by Richard Bradley.  [ruby-trunk - Bug #7551]

* ext/openssl/ossl.c (class OpenSSL):  Use only inner parenthesis in
  create_extension examples.

History

#2 Updated by Martin Bosslet over 1 year ago

  • Category set to doc
  • Status changed from Open to Assigned
  • Assignee set to Martin Bosslet
  • Target version set to 2.0.0

Thanks, Richard!

#3 Updated by Eric Hodel over 1 year ago

Regarding your questions:

1) If the best we can do at present is point to a .h file in OpenSSL at present then I don't see a problem with it.

2) For OpenSSL::X509::ExtensionFactory, new documentation would go in ext/openssl/osslx509ext.c. For the most part the class or module implemented is guessable from the file name. You can look at ext/openssl/osslx509name.c for examples (or any of the .c files at the root).

PS: Your patch is great.

#4 Updated by Yusuke Endoh about 1 year ago

  • Target version changed from 2.0.0 to next minor

Is there any reason that the patch is not imported yet?

Yusuke Endoh mame@tsg.ne.jp

#5 Updated by Eric Hodel about 1 year ago

  • Assignee changed from Martin Bosslet to Eric Hodel

I will commit it.

#6 Updated by Eric Hodel about 1 year ago

  • Status changed from Assigned to Closed
  • % Done changed from 0 to 100

This issue was solved with changeset r39309.
Richard, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.


  • ext/openssl/ossl.c (class OpenSSL): Fixed ExtensionFactory example. Patch by Richard Bradley. [ruby-trunk - Bug #7551]

#7 Updated by Tomoyuki Chikanaga about 1 year ago

  • Tracker changed from Bug to Backport
  • Project changed from ruby-trunk to Backport200
  • Category deleted (doc)
  • Status changed from Closed to Assigned
  • Assignee changed from Eric Hodel to Tomoyuki Chikanaga
  • Target version deleted (next minor)

I'll merge r39309 and r39310 to rub20_0.

#8 Updated by Tomoyuki Chikanaga about 1 year ago

  • Status changed from Assigned to Closed

This issue was solved with changeset r39584.
Richard, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.


merge revision(s) 39309,39310: [Backport #7551]

* ext/openssl/ossl.c (class OpenSSL):  Fixed ExtensionFactory example.
  Patch by Richard Bradley.  [ruby-trunk - Bug #7551]

* ext/openssl/ossl.c (class OpenSSL):  Use only inner parenthesis in
  create_extension examples.

Also available in: Atom PDF