Ruby openssl documentation [closed]

Question

Is there any online documentation of Ruby's openssl library? All I can find are blog posts and third-party articles, and the rdoc itself doesn't really explain how to use the library step-by-step.

Answer 1

Some brave soul finally documented it in the latest versions of ruby. See github:

https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl.c#L409

EDIT: just to give credit where it's due, the commit history says that Eric Hodel is responsible for this good documentation.

Answer 2

This can only be a partial answer since I'm also looking to Ruby to use commercial grade HTTPS functionality. As background, I was tech-support engineer for EFT*POS and SmartCards some long time ago and an internal ad hoc reviewer for draft the CCITT X.600 standards. Fortunately, my area was secure-messaging and services (like API-s).

And while that was in another life ... I still remember things. I don't especially think it is the OpenSSL implementers' job to explain how-to-use an OpenSSL interface. At the same time, I believe I appreciate the frustration of 'starting' with any of this stuff.

And ... I definitely think it is important for published libraries, modules, gems, components and bits to be documented by humans. I only find RDoc and similar 'generated' documentation useful in a limited set of development or bug fix use cases. For example a library like OpenSSL 'might' point to SSL and TLS overviews and 'why' examples. I think it is vital that library and gem implementers engage with the idea that you are writing something that others will use to effect.

• Example: a hammer is used to effect to bang a nail and join two pieces of wood.

• That same hammer can also be used to impact the shell-casing of a bullet and cause serious outcomes. I prefer that Ruby Open SSL documetation begin with the meaning and impact of the tool, component or module. A good place to gain some background is with this post:

• How to Cure Net::HTTP’s Risky Default HTTPS Behavior, Peter Cooper (09-Oct-2010).
  Also, see:

• Always Verify SSL Certificates,
  And follow the steps shown for cURL command line so you will have a check for your machine's connection and the encoding.
• http://curl.haxx.se/docs/caextract.html

Earlier I tried pointing my Ruby test script to the CA-bundle cURL command line uses. That didn't work, whereas if I test without SSL verification and if I use cURL with SSL on the command line, life it good (again).

If that gets you started, let me know what the next step is. Sometimes the lack of documentation is because there is a work in progress and other times it is because good-looking, robust bits like OpenSSL just work. In this case 'we' (collectively) want to know how to apply best-practice in particular situations.

Join in encouraging (rewarding) people to engage with the idea or documenting things for others to be able and motivated to: use to effect.