1# BoringSSL Style Guide 2 3BoringSSL usually follows the 4[Google C++ style guide](https://google.github.io/styleguide/cppguide.html), 5The rest of this document describes differences and clarifications on 6top of the base guide. 7 8 9## Legacy code 10 11As a derivative of OpenSSL, BoringSSL contains a lot of legacy code that 12does not follow this style guide. Particularly where public API is 13concerned, balance consistency within a module with the benefits of a 14given rule. Module-wide deviations on naming should be respected while 15integer and return value conventions take precedence over consistency. 16 17Modules from OpenSSL's legacy ASN.1 and X.509 stack are retained for 18compatibility and left largely unmodified. To ease importing patches from 19upstream, they match OpenSSL's new indentation style. For Emacs, 20`doc/openssl-c-indent.el` from OpenSSL may be helpful in this. 21 22 23## Language 24 25The majority of the project is in C, so C++-specific rules in the 26Google style guide do not apply. Support for C99 features depends on 27our target platforms. Typically, Chromium's target MSVC is the most 28restrictive. 29 30Variable declarations in the middle of a function or inside a `for` loop are 31allowed and preferred where possible. Note that the common `goto err` cleanup 32pattern requires lifting some variable declarations. 33 34Comments should be `/* C-style */` for consistency. 35 36When declaration pointer types, `*` should be placed next to the variable 37name, not the type. So 38 39 uint8_t *ptr; 40 41not 42 43 uint8_t* ptr; 44 45Rather than `malloc()` and `free()`, use the wrappers `OPENSSL_malloc()` 46and `OPENSSL_free()`. Use the standard C `assert()` function freely. 47 48Use the following wrappers, found in `crypto/internal.h` instead of the 49corresponding C standard library functions. They behave the same but avoid 50confusing undefined behavior. 51 52* `OPENSSL_memchr` 53* `OPENSSL_memcmp` 54* `OPENSSL_memcpy` 55* `OPENSSL_memmove` 56* `OPENSSL_memset` 57 58For new constants, prefer enums when the values are sequential and typed 59constants for flags. If adding values to an existing set of `#define`s, 60continue with `#define`. 61 62 63## Formatting 64 65Single-statement blocks are not allowed. All conditions and loops must 66use braces: 67 68 if (foo) { 69 do_something(); 70 } 71 72not 73 74 if (foo) 75 do_something(); 76 77 78## Integers 79 80Prefer using explicitly-sized integers where appropriate rather than 81generic C ones. For instance, to represent a byte, use `uint8_t`, not 82`unsigned char`. Likewise, represent a two-byte field as `uint16_t`, not 83`unsigned short`. 84 85Sizes are represented as `size_t`. 86 87Within a struct that is retained across the lifetime of an SSL 88connection, if bounds of a size are known and it's easy, use a smaller 89integer type like `uint8_t`. This is a "free" connection footprint 90optimization for servers. Don't make code significantly more complex for 91it, and do still check the bounds when passing in and out of the 92struct. This narrowing should not propagate to local variables and 93function parameters. 94 95When doing arithmetic, account for overflow conditions. 96 97Except with platform APIs, do not use `ssize_t`. MSVC lacks it, and 98prefer out-of-band error signaling for `size_t` (see Return values). 99 100 101## Naming 102 103Follow Google naming conventions in C++ files. In C files, use the 104following naming conventions for consistency with existing OpenSSL and C 105styles: 106 107Define structs with typedef named `TYPE_NAME`. The corresponding struct 108should be named `struct type_name_st`. 109 110Name public functions as `MODULE_function_name`, unless the module 111already uses a different naming scheme for legacy reasons. The module 112name should be a type name if the function is a method of a particular 113type. 114 115Some types are allocated within the library while others are initialized 116into a struct allocated by the caller, often on the stack. Name these 117functions `TYPE_NAME_new`/`TYPE_NAME_free` and 118`TYPE_NAME_init`/`TYPE_NAME_cleanup`, respectively. All `TYPE_NAME_free` 119functions must do nothing on `NULL` input. 120 121If a variable is the length of a pointer value, it has the suffix 122`_len`. An output parameter is named `out` or has an `out_` prefix. For 123instance, For instance: 124 125 uint8_t *out, 126 size_t *out_len, 127 const uint8_t *in, 128 size_t in_len, 129 130Name public headers like `include/openssl/evp.h` with header guards like 131`OPENSSL_HEADER_EVP_H`. Name internal headers like 132`crypto/ec/internal.h` with header guards like 133`OPENSSL_HEADER_EC_INTERNAL_H`. 134 135Name enums like `enum unix_hacker_t`. For instance: 136 137 enum should_free_handshake_buffer_t { 138 free_handshake_buffer, 139 dont_free_handshake_buffer, 140 }; 141 142 143## Return values 144 145As even `malloc` may fail in BoringSSL, the vast majority of functions 146will have a failure case. Functions should return `int` with one on 147success and zero on error. Do not overload the return value to both 148signal success/failure and output an integer. For example: 149 150 OPENSSL_EXPORT int CBS_get_u16(CBS *cbs, uint16_t *out); 151 152If a function needs more than a true/false result code, define an enum 153rather than arbitrarily assigning meaning to int values. 154 155If a function outputs a pointer to an object on success and there are no 156other outputs, return the pointer directly and `NULL` on error. 157 158 159## Parameters 160 161Where not constrained by legacy code, parameter order should be: 162 1631. context parameters 1642. output parameters 1653. input parameters 166 167For example, 168 169 /* CBB_add_asn sets |*out_contents| to a |CBB| into which the contents of an 170 * ASN.1 object can be written. The |tag| argument will be used as the tag for 171 * the object. It returns one on success or zero on error. */ 172 OPENSSL_EXPORT int CBB_add_asn1(CBB *cbb, CBB *out_contents, unsigned tag); 173 174 175## Documentation 176 177All public symbols must have a documentation comment in their header 178file. The style is based on that of Go. The first sentence begins with 179the symbol name, optionally prefixed with "A" or "An". Apart from the 180initial mention of symbol, references to other symbols or parameter 181names should be surrounded by |pipes|. 182 183Documentation should be concise but completely describe the exposed 184behavior of the function. Pay special note to success/failure behaviors 185and caller obligations on object lifetimes. If this sacrifices 186conciseness, consider simplifying the function's behavior. 187 188 /* EVP_DigestVerifyUpdate appends |len| bytes from |data| to the data which 189 * will be verified by |EVP_DigestVerifyFinal|. It returns one on success and 190 * zero otherwise. */ 191 OPENSSL_EXPORT int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *data, 192 size_t len); 193 194Explicitly mention any surprising edge cases or deviations from common 195return value patterns in legacy functions. 196 197 /* RSA_private_encrypt encrypts |flen| bytes from |from| with the private key in 198 * |rsa| and writes the encrypted data to |to|. The |to| buffer must have at 199 * least |RSA_size| bytes of space. It returns the number of bytes written, or 200 * -1 on error. The |padding| argument must be one of the |RSA_*_PADDING| 201 * values. If in doubt, |RSA_PKCS1_PADDING| is the most common. 202 * 203 * WARNING: this function is dangerous because it breaks the usual return value 204 * convention. Use |RSA_sign_raw| instead. */ 205 OPENSSL_EXPORT int RSA_private_encrypt(int flen, const uint8_t *from, 206 uint8_t *to, RSA *rsa, int padding); 207 208Document private functions in their `internal.h` header or, if static, 209where defined. 210