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

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_load_RAND_strings does nothing.

OPENSSL_EXPORT void ERR_load_RAND_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.

OPENSSL_INLINE int ERR_GET_LIB(uint32_t packed_error) {
  return (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.

OPENSSL_INLINE int ERR_GET_REASON(uint32_t packed_error) {
  return (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_FLAG_MALLOCED is passed into ERR_set_error_data to indicate that data was allocated with OPENSSL_malloc.

It is, separately, returned in *flags from ERR_get_error_line_data to indicate that *data has a non-static lifetime, but this lifetime is still managed by the library. The caller must not call OPENSSL_free or free on data.

#define ERR_FLAG_MALLOCED 2

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, places it at buf, and returns 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 char *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, or a placeholder string is the library is unrecognized.

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, or a placeholder string if the reason is unrecognized.

OPENSSL_EXPORT const char *ERR_reason_error_string(uint32_t packed_error);

ERR_lib_symbol_name returns the symbol name of library that generated packed_error, or NULL if unrecognized. For example, an error from ERR_LIB_EVP would return "EVP".

OPENSSL_EXPORT const char *ERR_lib_symbol_name(uint32_t packed_error);

ERR_reason_symbol_name returns the symbol name of the reason for packed_error, or NULL if unrecognized. For example, ERR_R_INTERNAL_ERROR would return "INTERNAL_ERROR".

Errors from the ERR_LIB_SYS library are typically errno values and will return NULL. User-defined errors will also return NULL.

OPENSSL_EXPORT const char *ERR_reason_symbol_name(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_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_TRUST_TOKEN,
  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
#define ERR_R_TRUST_TOKEN_LIB ERR_LIB_TRUST_TOKEN

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_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.

Use ERR_clear_error instead. Note error queues are deleted automatically on thread exit. You do not need to call this function to release memory.

OPENSSL_EXPORT void ERR_remove_thread_state(const CRYPTO_THREADID *tid);

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.

Additionally, if buf is NULL, the error string is placed in a static buffer which is returned. This is not thread-safe and only exists for backwards compatibility with legacy callers. The static buffer will be overridden by calls in other threads.

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 120

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

OPENSSL_INLINE int ERR_GET_FUNC(uint32_t packed_error) {
  (void)packed_error;
  return 0;
}

ERR_TXT_* are provided for compatibility with code that assumes that it's using OpenSSL.

#define ERR_TXT_STRING ERR_FLAG_STRING
#define ERR_TXT_MALLOCED ERR_FLAG_MALLOCED