err.h

All headers

Error queue handling functions.

Errors in OpenSSL are generally signaled by the return value of a function. When a function fails it may add an entry to a per-thread error queue, which is managed by the functions in this header.

Each error contains: 1) The library (i.e. ec, pem, rsa) which created it. 2) The file and line number of the call that added the error. 3) A pointer to some error specific data, which may be NULL.

The library identifier and reason code are packed in a uint32_t and there exist various functions for unpacking it.

The typical behaviour is that an error will occur deep in a call queue and that code will push an error onto the error queue. As the error queue unwinds, other functions will push their own errors. Thus, the "least recent" error is the most specific and the other errors will provide a backtrace of sorts.

  1. Startup and shutdown
  2. ERR_load_BIO_strings
  3. ERR_load_ERR_strings
  4. ERR_load_crypto_strings
  5. ERR_free_strings
  6. Reading and formatting errors
  7. ERR_GET_LIB
  8. ERR_GET_REASON
  9. ERR_get_error
  10. ERR_get_error_line
  11. ERR_FLAG_STRING
  12. ERR_get_error_line_data
  13. ERR_peek_error
  14. ERR_peek_error_line
  15. ERR_peek_error_line_data
  16. ERR_peek_last_error
  17. ERR_peek_last_error_line
  18. ERR_peek_last_error_line_data
  19. ERR_error_string_n
  20. ERR_lib_error_string
  21. ERR_reason_error_string
  22. ERR_print_errors_cb
  23. ERR_print_errors_fp
  24. Clearing errors
  25. ERR_clear_error
  26. ERR_remove_thread_state
  27. ERR_set_mark
  28. ERR_pop_to_mark
  29. Custom errors
  30. ERR_get_next_error_library
  31. Built-in library and reason codes
  32. {
  33. ERR_R_SYS_LIB
  34. ERR_R_BN_LIB
  35. ERR_R_RSA_LIB
  36. ERR_R_DH_LIB
  37. ERR_R_EVP_LIB
  38. ERR_R_BUF_LIB
  39. ERR_R_OBJ_LIB
  40. ERR_R_PEM_LIB
  41. ERR_R_DSA_LIB
  42. ERR_R_X509_LIB
  43. ERR_R_ASN1_LIB
  44. ERR_R_CONF_LIB
  45. ERR_R_CRYPTO_LIB
  46. ERR_R_EC_LIB
  47. ERR_R_SSL_LIB
  48. ERR_R_BIO_LIB
  49. ERR_R_PKCS7_LIB
  50. ERR_R_PKCS8_LIB
  51. ERR_R_X509V3_LIB
  52. ERR_R_RAND_LIB
  53. ERR_R_DSO_LIB
  54. ERR_R_ENGINE_LIB
  55. ERR_R_OCSP_LIB
  56. ERR_R_UI_LIB
  57. ERR_R_COMP_LIB
  58. ERR_R_ECDSA_LIB
  59. ERR_R_ECDH_LIB
  60. ERR_R_STORE_LIB
  61. ERR_R_FIPS_LIB
  62. ERR_R_CMS_LIB
  63. ERR_R_TS_LIB
  64. ERR_R_HMAC_LIB
  65. ERR_R_JPAKE_LIB
  66. ERR_R_USER_LIB
  67. ERR_R_DIGEST_LIB
  68. ERR_R_CIPHER_LIB
  69. ERR_R_HKDF_LIB
  70. ERR_R_FATAL
  71. ERR_R_MALLOC_FAILURE
  72. ERR_R_SHOULD_NOT_HAVE_BEEN_CALLED
  73. ERR_R_PASSED_NULL_PARAMETER
  74. ERR_R_INTERNAL_ERROR
  75. ERR_R_OVERFLOW
  76. Deprecated functions
  77. ERR_remove_state
  78. ERR_func_error_string
  79. ERR_error_string
  80. ERR_ERROR_STRING_BUF_LEN
  81. ERR_GET_FUNC
  82. ERR_TXT_STRING

Startup and shutdown.

ERR_load_BIO_strings does nothing.

TODO(fork): remove. libjingle calls this.

OPENSSL_EXPORT void ERR_load_BIO_strings(void);

ERR_load_ERR_strings does nothing.

OPENSSL_EXPORT void ERR_load_ERR_strings(void);

ERR_load_crypto_strings does nothing.

OPENSSL_EXPORT void ERR_load_crypto_strings(void);

ERR_free_strings does nothing.

OPENSSL_EXPORT void ERR_free_strings(void);

Reading and formatting errors.

ERR_GET_LIB returns the library code for the error. This is one of the ERR_LIB_* values.

#define ERR_GET_LIB(packed_error) ((int)(((packed_error) >> 24) & 0xff))

ERR_GET_REASON returns the reason code for the error. This is one of library-specific LIB_R_* values where LIB is the library (see ERR_GET_LIB). Note that reason codes are specific to the library.

#define ERR_GET_REASON(packed_error) ((int)((packed_error) & 0xfff))

ERR_get_error gets the packed error code for the least recent error and removes that error from the queue. If there are no errors in the queue then it returns zero.

OPENSSL_EXPORT uint32_t ERR_get_error(void);

ERR_get_error_line acts like ERR_get_error, except that the file and line number of the call that added the error are also returned.

OPENSSL_EXPORT uint32_t ERR_get_error_line(const char **file, int *line);

ERR_FLAG_STRING means that the data member is a NUL-terminated string that can be printed. This is always set if data is non-NULL.

#define ERR_FLAG_STRING 1

ERR_get_error_line_data acts like ERR_get_error_line, but also returns the error-specific data pointer and flags. The flags are a bitwise-OR of ERR_FLAG_* values. The error-specific data is owned by the error queue and the pointer becomes invalid after the next call that affects the same thread's error queue. If *flags contains ERR_FLAG_STRING then *data is human-readable.

OPENSSL_EXPORT uint32_t ERR_get_error_line_data(const char **file, int *line,
                                                const char **data, int *flags);

The "peek" functions act like the ERR_get_error functions, above, but they do not remove the error from the queue.

OPENSSL_EXPORT uint32_t ERR_peek_error(void);
OPENSSL_EXPORT uint32_t ERR_peek_error_line(const char **file, int *line);
OPENSSL_EXPORT uint32_t ERR_peek_error_line_data(const char **file, int *line,
                                                 const char **data, int *flags);

The "peek last" functions act like the "peek" functions, above, except that they return the most recent error.

OPENSSL_EXPORT uint32_t ERR_peek_last_error(void);
OPENSSL_EXPORT uint32_t ERR_peek_last_error_line(const char **file, int *line);
OPENSSL_EXPORT uint32_t ERR_peek_last_error_line_data(const char **file,
                                                      int *line,
                                                      const char **data,
                                                      int *flags);

ERR_error_string_n generates a human-readable string representing packed_error and places it at buf. It writes at most len bytes (including the terminating NUL) and truncates the string if necessary. If len is greater than zero then buf is always NUL terminated.

The string will have the following format:

error:[error code]:[library name]:OPENSSL_internal:[reason string]

error code is an 8 digit hexadecimal number; library name and reason string are ASCII text.

OPENSSL_EXPORT void ERR_error_string_n(uint32_t packed_error, char *buf,
                                       size_t len);

ERR_lib_error_string returns a string representation of the library that generated packed_error.

OPENSSL_EXPORT const char *ERR_lib_error_string(uint32_t packed_error);

ERR_reason_error_string returns a string representation of the reason for packed_error.

OPENSSL_EXPORT const char *ERR_reason_error_string(uint32_t packed_error);

ERR_print_errors_callback_t is the type of a function used by ERR_print_errors_cb. It takes a pointer to a human readable string (and its length) that describes an entry in the error queue. The ctx argument is an opaque pointer given to ERR_print_errors_cb.

It should return one on success or zero on error, which will stop the iteration over the error queue.

typedef int (*ERR_print_errors_callback_t)(const char *str, size_t len,
                                           void *ctx);

ERR_print_errors_cb clears the current thread's error queue, calling callback with a string representation of each error, from the least recent to the most recent error.

The string will have the following format (which differs from ERR_error_string):

[thread id]:error:[error code]:[library name]:OPENSSL_internal:[reason string]:[file]:[line number]:[optional string data]

The callback can return one to continue the iteration or zero to stop it. The ctx argument is an opaque value that is passed through to the callback.

OPENSSL_EXPORT void ERR_print_errors_cb(ERR_print_errors_callback_t callback,
                                        void *ctx);

ERR_print_errors_fp clears the current thread's error queue, printing each error to file. See ERR_print_errors_cb for the format.

OPENSSL_EXPORT void ERR_print_errors_fp(FILE *file);

Clearing errors.

ERR_clear_error clears the error queue for the current thread.

OPENSSL_EXPORT void ERR_clear_error(void);

ERR_remove_thread_state clears the error queue for the current thread if tid is NULL. Otherwise it calls assert(0), because it's no longer possible to delete the error queue for other threads.

Error queues are thread-local data and are deleted automatically. You do not need to call this function. Use ERR_clear_error.

OPENSSL_EXPORT void ERR_remove_thread_state(const CRYPTO_THREADID *tid);

ERR_set_mark "marks" the most recent error for use with ERR_pop_to_mark. It returns one if an error was marked and zero if there are no errors.

OPENSSL_EXPORT int ERR_set_mark(void);

ERR_pop_to_mark removes errors from the most recent to the least recent until (and not including) a "marked" error. It returns zero if no marked error was found (and thus all errors were removed) and one otherwise. Errors are marked using ERR_set_mark.

OPENSSL_EXPORT int ERR_pop_to_mark(void);

Custom errors.

ERR_get_next_error_library returns a value suitable for passing as the library argument to ERR_put_error. This is intended for code that wishes to push its own, non-standard errors to the error queue.

OPENSSL_EXPORT int ERR_get_next_error_library(void);

Built-in library and reason codes.

The following values are built-in library codes.

enum {
  ERR_LIB_NONE = 1,
  ERR_LIB_SYS,
  ERR_LIB_BN,
  ERR_LIB_RSA,
  ERR_LIB_DH,
  ERR_LIB_EVP,
  ERR_LIB_BUF,
  ERR_LIB_OBJ,
  ERR_LIB_PEM,
  ERR_LIB_DSA,
  ERR_LIB_X509,
  ERR_LIB_ASN1,
  ERR_LIB_CONF,
  ERR_LIB_CRYPTO,
  ERR_LIB_EC,
  ERR_LIB_SSL,
  ERR_LIB_BIO,
  ERR_LIB_PKCS7,
  ERR_LIB_PKCS8,
  ERR_LIB_X509V3,
  ERR_LIB_RAND,
  ERR_LIB_ENGINE,
  ERR_LIB_OCSP,
  ERR_LIB_UI,
  ERR_LIB_COMP,
  ERR_LIB_ECDSA,
  ERR_LIB_ECDH,
  ERR_LIB_HMAC,
  ERR_LIB_DIGEST,
  ERR_LIB_CIPHER,
  ERR_LIB_HKDF,
  ERR_LIB_USER,
  ERR_NUM_LIBS
};

The following reason codes used to denote an error occuring in another library. They are sometimes used for a stack trace.

#define ERR_R_SYS_LIB ERR_LIB_SYS
#define ERR_R_BN_LIB ERR_LIB_BN
#define ERR_R_RSA_LIB ERR_LIB_RSA
#define ERR_R_DH_LIB ERR_LIB_DH
#define ERR_R_EVP_LIB ERR_LIB_EVP
#define ERR_R_BUF_LIB ERR_LIB_BUF
#define ERR_R_OBJ_LIB ERR_LIB_OBJ
#define ERR_R_PEM_LIB ERR_LIB_PEM
#define ERR_R_DSA_LIB ERR_LIB_DSA
#define ERR_R_X509_LIB ERR_LIB_X509
#define ERR_R_ASN1_LIB ERR_LIB_ASN1
#define ERR_R_CONF_LIB ERR_LIB_CONF
#define ERR_R_CRYPTO_LIB ERR_LIB_CRYPTO
#define ERR_R_EC_LIB ERR_LIB_EC
#define ERR_R_SSL_LIB ERR_LIB_SSL
#define ERR_R_BIO_LIB ERR_LIB_BIO
#define ERR_R_PKCS7_LIB ERR_LIB_PKCS7
#define ERR_R_PKCS8_LIB ERR_LIB_PKCS8
#define ERR_R_X509V3_LIB ERR_LIB_X509V3
#define ERR_R_RAND_LIB ERR_LIB_RAND
#define ERR_R_DSO_LIB ERR_LIB_DSO
#define ERR_R_ENGINE_LIB ERR_LIB_ENGINE
#define ERR_R_OCSP_LIB ERR_LIB_OCSP
#define ERR_R_UI_LIB ERR_LIB_UI
#define ERR_R_COMP_LIB ERR_LIB_COMP
#define ERR_R_ECDSA_LIB ERR_LIB_ECDSA
#define ERR_R_ECDH_LIB ERR_LIB_ECDH
#define ERR_R_STORE_LIB ERR_LIB_STORE
#define ERR_R_FIPS_LIB ERR_LIB_FIPS
#define ERR_R_CMS_LIB ERR_LIB_CMS
#define ERR_R_TS_LIB ERR_LIB_TS
#define ERR_R_HMAC_LIB ERR_LIB_HMAC
#define ERR_R_JPAKE_LIB ERR_LIB_JPAKE
#define ERR_R_USER_LIB ERR_LIB_USER
#define ERR_R_DIGEST_LIB ERR_LIB_DIGEST
#define ERR_R_CIPHER_LIB ERR_LIB_CIPHER
#define ERR_R_HKDF_LIB ERR_LIB_HKDF

The following values are global reason codes. They may occur in any library.

#define ERR_R_FATAL 64
#define ERR_R_MALLOC_FAILURE (1 | ERR_R_FATAL)
#define ERR_R_SHOULD_NOT_HAVE_BEEN_CALLED (2 | ERR_R_FATAL)
#define ERR_R_PASSED_NULL_PARAMETER (3 | ERR_R_FATAL)
#define ERR_R_INTERNAL_ERROR (4 | ERR_R_FATAL)
#define ERR_R_OVERFLOW (5 | ERR_R_FATAL)

Deprecated functions.

ERR_remove_state calls ERR_clear_error.

OPENSSL_EXPORT void ERR_remove_state(unsigned long pid);

ERR_func_error_string returns the string "OPENSSL_internal".

OPENSSL_EXPORT const char *ERR_func_error_string(uint32_t packed_error);

ERR_error_string behaves like ERR_error_string_n but len is implicitly ERR_ERROR_STRING_BUF_LEN and it returns buf. If buf is NULL, the error string is placed in a static buffer which is returned. (The static buffer may be overridden by concurrent calls in other threads so this form should not be used.)

Use ERR_error_string_n instead.

TODO(fork): remove this function.

OPENSSL_EXPORT char *ERR_error_string(uint32_t packed_error, char *buf);
#define ERR_ERROR_STRING_BUF_LEN 256

ERR_GET_FUNC returns zero. BoringSSL errors do not report a function code.

#define ERR_GET_FUNC(packed_error) 0

ERR_TXT_STRING is provided for compatibility with code that assumes that it's using OpenSSL.

#define ERR_TXT_STRING ERR_FLAG_STRING