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