Library Errors

OpenSSL is a library which helps you develop reliable and secure programs when using SSL and TLS protocols. The library is complex and will encounter failures on occasion. The errors often fall into one of two categories: failing to use an API correctly and errors when using a particular protocol. While errors are sometimes unexpected, the recovery should be well planned.

The first type of errors, caused by the failure to use APIs correctly, will result in a crash or errant behavior. For example, ignoring the return value from ENGINE_by_id will result in a crash because a subsequent call will dereference a NULL pointer (ENGINE_set_default is a macro). Other APIs, such as RAND_bytes return 1 for success, and 0 otherwise. Ignoring the function's return value means you risk using non-random data where you expected cryptographically secure random data. Yet other APIs will allow an adversary to escalate privileges (you did not think only good guys would use your program, did you?). For example, Android's Gingerbreak (also known as adb setuid exhaustion), took advantage of ignoring return values from setgid and setuid.

The second set of errors results from external failures, such as DNS, SSL, or TLS. These failures are sometimes transient (meaning they come and go), so they can be a bit more difficult to detect and recover. Other external failures include items such as self-signed certificates without a corresponding certificate or public key in a trusted store. Depending on the API set being used, you will retrieve error information in different ways. For example, if using the FIPS or ENIGNE routines, you will use ERR_get_error to retrieve error information. If you are validating a connection or certificate, you will use SSL_get_error, SSL_get_verify_result, or X509_STORE_CTX_get_error.

Properly detecting and recovering from error conditions will help increase reliability and security in your programs, and offer the user a more pleasant experience.

== libcrypto Usage ==