Difference between revisions of "Library Errors"

From OpenSSLWiki
Jump to navigationJump to search
(Created page with "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 er…")
 
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
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 and API correctly and errors when using a particular protocol. While errors are sometimes unexpected, the recovery should be well planned.
+
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 <tt>ENGINE_by_id</tt> will result in a crash because a subsequent call will dereference a <tt>NULL</tt> pointer (<tt>ENGINE_set_default</tt> is a macro). Other APIs, such as <tt>RAND_bytes</tt> 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 ''[http://www.apriorit.com/our-company/dev-blog/255-android-rooting adb setuid exhaustion]''), took advantage of ignoring return values from <tt>setgid</tt> and <tt>setuid</tt>.
 
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 <tt>ENGINE_by_id</tt> will result in a crash because a subsequent call will dereference a <tt>NULL</tt> pointer (<tt>ENGINE_set_default</tt> is a macro). Other APIs, such as <tt>RAND_bytes</tt> 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 ''[http://www.apriorit.com/our-company/dev-blog/255-android-rooting adb setuid exhaustion]''), took advantage of ignoring return values from <tt>setgid</tt> and <tt>setuid</tt>.
Line 6: Line 6:
  
 
Properly detecting and recovering from error conditions will help increase reliability and security in your programs, and offer the user a more pleasant experience.
 
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 ==
 +
 +
== libssl Usage ==
 +
 +
== Miscellaneous ==
 +
 +
== See also ==
 +
* [[Libcrypto API]]
 +
* [[Libssl API]]
 +
 +
[[Category:ssl API]]
 +
[[Category:Crypto API]]

Latest revision as of 17:29, 24 March 2013

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[edit]

libssl Usage[edit]

Miscellaneous[edit]

See also[edit]