Home | History | Annotate | Download | only in src
      1 # BoringSSL API Conventions
      2 
      3 This document describes conventions for BoringSSL APIs. The [style
      4 guide](/STYLE.md) also includes guidelines, but this document is targeted at
      5 both API consumers and developers.
      6 
      7 
      8 ## Documentation
      9 
     10 All supported public APIs are documented in the public header files, found in
     11 `include/openssl`. The API documentation is also available
     12 [online](https://commondatastorage.googleapis.com/chromium-boringssl-docs/headers.html).
     13 
     14 Some headers lack documention comments. These are functions and structures from
     15 OpenSSL's legacy ASN.1, X.509, and PEM implementation. If possible, avoid using
     16 them. These are left largely unmodified from upstream and are retained only for
     17 compatibility with existing OpenSSL consumers.
     18 
     19 
     20 ## Forward declarations
     21 
     22 Do not write `typedef struct foo_st FOO` or try otherwise to define BoringSSL's
     23 types. Including `openssl/base.h` (or `openssl/ossl_typ.h` for consumers who
     24 wish to be OpenSSL-compatible) will forward-declare each type without importing
     25 the rest of the library or invasive macros.
     26 
     27 
     28 ## Error-handling
     29 
     30 Most functions in BoringSSL may fail, either due to allocation failures or input
     31 errors. Functions which return an `int` typically return one on success and zero
     32 on failure. Functions which return a pointer typically return `NULL` on failure.
     33 However, due to legacy constraints, some functions are more complex. Consult the
     34 API documentation before using a function.
     35 
     36 On error, most functions also push errors on the error queue, an `errno`-like
     37 mechanism. See the documentation for
     38 [err.h](https://commondatastorage.googleapis.com/chromium-boringssl-docs/err.h.html)
     39 for more details.
     40 
     41 As with `errno`, callers must test the function's return value, not the error
     42 queue to determine whether an operation failed. Some codepaths may not interact
     43 with the error queue, and the error queue may have state from a previous failed
     44 operation.
     45 
     46 When ignoring a failed operation, it is recommended to call `ERR_clear_error` to
     47 avoid the state interacting with future operations. Failing to do so should not
     48 affect the actual behavior of any functions, but may result in errors from both
     49 operations being mixed in error logging. We hope to
     50 [improve](https://bugs.chromium.org/p/boringssl/issues/detail?id=38) this
     51 situation in the future.
     52 
     53 Where possible, avoid conditioning on specific reason codes and limit usage to
     54 logging. The reason codes are very specific and may change over time.
     55 
     56 
     57 ## Memory allocation
     58 
     59 BoringSSL allocates memory via `OPENSSL_malloc`, found in `mem.h`. Use
     60 `OPENSSL_free`, found in the same header file, to release it. BoringSSL
     61 functions will fail gracefully on allocation error, but it is recommended to use
     62 a `malloc` implementation that `abort`s on failure.
     63 
     64 
     65 ## Object initialization and cleanup
     66 
     67 BoringSSL defines a number of structs for use in its APIs. It is a C library,
     68 so the caller is responsible for ensuring these structs are properly
     69 initialized and released. Consult the documentation for a module for the
     70 proper use of its types. Some general conventions are listed below.
     71 
     72 
     73 ### Heap-allocated types
     74 
     75 Some types, such as `RSA`, are heap-allocated. All instances will be allocated
     76 and returned from BoringSSL's APIs. It is an error to instantiate a heap-
     77 allocated type on the stack or embedded within another object.
     78 
     79 Heap-allocated types may have functioned named like `RSA_new` which allocates a
     80 fresh blank `RSA`. Other functions may also return newly-allocated instances.
     81 For example, `RSA_parse_public_key` is documented to return a newly-allocated
     82 `RSA` object.
     83 
     84 Heap-allocated objects must be released by the corresponding free function,
     85 named like `RSA_free`. Like C's `free` and C++'s `delete`, all free functions
     86 internally check for `NULL`. Consumers are not required to check for `NULL`
     87 before calling.
     88 
     89 A heap-allocated type may be reference-counted. In this case, a function named
     90 like `RSA_up_ref` will be available to take an additional reference count. The
     91 free function must be called to decrement the reference count. It will only
     92 release resources when the final reference is released. For OpenSSL
     93 compatibility, these functions return `int`, but callers may assume they always
     94 successfully return one because reference counts use saturating arithmetic.
     95 
     96 C++ consumers are recommended to use `bssl::UniquePtr` to manage heap-allocated
     97 objects. `bssl::UniquePtr<T>`, like other types, is forward-declared in
     98 `openssl/base.h`. Code that needs access to the free functions, such as code
     99 which destroys a `bssl::UniquePtr`, must include the corresponding module's
    100 header. (This matches `std::unique_ptr`'s relationship with forward
    101 declarations.)
    102 
    103 
    104 ### Stack-allocated types
    105 
    106 Other types in BoringSSL are stack-allocated, such as `EVP_MD_CTX`. These
    107 types may be allocated on the stack or embedded within another object.
    108 However, they must still be initialized before use.
    109 
    110 Every stack-allocated object in BoringSSL has a *zero state*, analogous to
    111 initializing a pointer to `NULL`. In this state, the object may not be
    112 completely initialized, but it is safe to call cleanup functions. Entering the
    113 zero state cannot fail. (It is usually `memset(0)`.)
    114 
    115 The function to enter the zero state is named like `EVP_MD_CTX_init` or
    116 `CBB_zero` and will always return `void`. To release resources associated with
    117 the type, call the cleanup function, named like `EVP_MD_CTX_cleanup`. The
    118 cleanup function must be called on all codepaths, regardless of success or
    119 failure. For example:
    120 
    121     uint8_t md[EVP_MAX_MD_SIZE];
    122     unsigned md_len;
    123     EVP_MD_CTX ctx;
    124     EVP_MD_CTX_init(&ctx);  /* Enter the zero state. */
    125     int ok = EVP_DigestInit_ex(&ctx, EVP_sha256(), NULL) &&
    126              EVP_DigestUpdate(&ctx, "hello ", 6) &&
    127              EVP_DigestUpdate(&ctx, "world", 5) &&
    128              EVP_DigestFinal_ex(&ctx, md, &md_len);
    129     EVP_MD_CTX_cleanup(&ctx);  /* Release |ctx|. */
    130 
    131 Note that `EVP_MD_CTX_cleanup` is called whether or not the `EVP_Digest*`
    132 operations succeeded. More complex C functions may use the `goto err` pattern:
    133 
    134       int ret = 0;
    135       EVP_MD_CTX ctx;
    136       EVP_MD_CTX_init(&ctx);
    137 
    138       if (!some_other_operation()) {
    139         goto err;
    140       }
    141 
    142       uint8_t md[EVP_MAX_MD_SIZE];
    143       unsigned md_len;
    144       if (!EVP_DigestInit_ex(&ctx, EVP_sha256(), NULL) ||
    145           !EVP_DigestUpdate(&ctx, "hello ", 6) ||
    146           !EVP_DigestUpdate(&ctx, "world", 5) ||
    147           !EVP_DigestFinal_ex(&ctx, md, &md_len) {
    148         goto err;
    149       }
    150 
    151       ret = 1;
    152 
    153     err:
    154       EVP_MD_CTX_cleanup(&ctx);
    155       return ret;
    156 
    157 Note that, because `ctx` is set to the zero state before any failures,
    158 `EVP_MD_CTX_cleanup` is safe to call even if the first operation fails before
    159 `EVP_DigestInit_ex`. However, it would be illegal to move the `EVP_MD_CTX_init`
    160 below the `some_other_operation` call.
    161 
    162 As a rule of thumb, enter the zero state of stack-allocated structs in the
    163 same place they are declared.
    164 
    165 C++ consumers are recommended to use the wrappers named like
    166 `bssl::ScopedEVP_MD_CTX`, defined in the corresponding module's header. These
    167 wrappers are automatically initialized to the zero state and are automatically
    168 cleaned up.
    169 
    170 
    171 ### Data-only types
    172 
    173 A few types, such as `SHA_CTX`, are data-only types and do not require cleanup.
    174 These are usually for low-level cryptographic operations. These types may be
    175 used freely without special cleanup conventions.
    176 
    177 
    178 ## Thread safety
    179 
    180 BoringSSL is internally aware of the platform threading library and calls into
    181 it as needed. Consult the API documentation for the threading guarantees of
    182 particular objects. In general, stateless reference-counted objects like `RSA`
    183 or `EVP_PKEY` which represent keys may typically be used from multiple threads
    184 simultaneously, provided no thread mutates the key.
    185