3

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?

  • 4
    It's unclear what you are expecting of us. If you need clarity on why great libraries often have less than stellar documentation, it's because writing libraries is more interesting than writing documentation. – Robert Harvey Nov 17 '16 at 3:08
  • 1
    duplicate of Why do so many libraries have no/poor documentation? – gnat Nov 17 '16 at 8:55
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.

  • Yeah it was awesome, I called this and got an error -2. Who the hell knows what that means? After an hour on stack overflow, bits must be 128 in order for this to work (no other number works). Why? I have no idea. This sparked my rage question. Take your rep. – Sanchke Dellowar Nov 17 '16 at 15:17

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.