Where is the OpenSSL documentation?

Question

I've noticed alot of hatred about OpenSSL because of it's lack of documentation. And all advice and guide about the library must be passed around our people in song and story.

I always doubt myself, because how could hundreds of people put so much time into this wonderful work of engineering if they don't even write down what it does? Is the official documentation a mere legend now? Sure there's openssl.org, and the pdf documentation; however it's not function by function, the documentation simply ballparks groups of functions at a time.

For instance, I'm trying to figure how to use the functionAES_set_encrypt_key(const unsigned char *userKey, const int bits,AES_KEY *key);.

• Header file has 0 lines of documentation,
• The website does not acknowledge it's existence,
• The PDF says the function exists, but it even spares me the detail of what the agruments are, making the header file more valuable

It could simply be I'm supposed to automatically know what this function does. I'm not that smart, indeed, but all in all though it adds friction when trying to learn this stuff.

Why does important documentation like this disappear/cease to exists?

Answer 1

Why does important documentation like this disappear/cease to exist?

Because this is an imperfect world full of imperfect people doing imperfect things, imperfectly.

A tiny bit of searching on google shows it used to have this header and a slightly different signature.

/* AES_set_encrypt_key configures |aeskey| to encrypt with the |bits|-bit key,
 * |key|.
 *
 * WARNING: unlike other OpenSSL functions, this returns zero on success and a
 * negative number on error. */
OPENSSL_EXPORT int AES_set_encrypt_key(const uint8_t *key, unsigned bits,
                                       AES_KEY *aeskey);

But since headers don't compile they often miss out on refactoring. With the signature change, that may have happened here. And they may have realized the headers were out of date afterwards so they just removed them.

Therefor I'll tell you to do here what you should do with all documentation: use with caution.