Backport #7551: Incorrect suggested usage in OpenSSL::X509::ExtensionFactory documentation

• Status: Closed
• Assignee: nagachika (Tomoyuki Chikanaga)

[richard.bradley (Richard Bradley)]

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 "extension_factory.create_extension" 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.)

[richard.bradley (Richard Bradley)]

• File fix-etension-factory-docs.diff fix-etension-factory-docs.diff added

[MartinBosslet (Martin Bosslet)]

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

Thanks, Richard!

[drbrain (Eric Hodel)]

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/ossl_x509ext.c. For the most part the class or module implemented is guessable from the file name. You can look at ext/openssl/ossl_x509name.c for examples (or any of the .c files at the root).

PS: Your patch is great.

[mame (Yusuke Endoh)]

• Target version changed from 2.0.0 to 2.6

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

--
Yusuke Endoh [e-mail]

[drbrain (Eric Hodel)]

• Assignee changed from MartinBosslet (Martin Bosslet) to drbrain (Eric Hodel)

I will commit it.

[drbrain (Eric Hodel)]

• 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]

[nagachika (Tomoyuki Chikanaga)]

• Tracker changed from Bug to Backport
• Project changed from Ruby master to Backport200
• Category deleted (doc)
• Status changed from Closed to Assigned
• Assignee changed from drbrain (Eric Hodel) to nagachika (Tomoyuki Chikanaga)
• Target version deleted (2.6)

I'll merge r39309 and r39310 to rub_2_0_0.

[nagachika (Tomoyuki Chikanaga)]

• 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.