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
17Some modules have seen few changes, so they still retain the original
18indentation style for now. When editing these, try to retain the
19original style. For Emacs, `doc/c-indentation.el` from OpenSSL may be
20helpful 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 are allowed.
31
32Comments should be `/* C-style */` for consistency.
33
34When declaration pointer types, `*` should be placed next to the variable
35name, not the type. So
36
37    uint8_t *ptr;
38
39not
40
41    uint8_t* ptr;
42
43Rather than `malloc()` and `free()`, use the wrappers `OPENSSL_malloc()`
44and `OPENSSL_free()`. Use the standard C `assert()` function freely.
45
46For new constants, prefer enums when the values are sequential and typed
47constants for flags. If adding values to an existing set of `#define`s,
48continue with `#define`.
49
50
51## Formatting
52
53Single-statement blocks are not allowed. All conditions and loops must
54use braces:
55
56    if (foo) {
57      do_something();
58    }
59
60not
61
62    if (foo)
63      do_something();
64
65
66## Integers
67
68Prefer using explicitly-sized integers where appropriate rather than
69generic C ones. For instance, to represent a byte, use `uint8_t`, not
70`unsigned char`. Likewise, represent a two-byte field as `uint16_t`, not
71`unsigned short`.
72
73Sizes are represented as `size_t`.
74
75Within a struct that is retained across the lifetime of an SSL
76connection, if bounds of a size are known and it's easy, use a smaller
77integer type like `uint8_t`. This is a "free" connection footprint
78optimization for servers. Don't make code significantly more complex for
79it, and do still check the bounds when passing in and out of the
80struct. This narrowing should not propagate to local variables and
81function parameters.
82
83When doing arithmetic, account for overflow conditions.
84
85Except with platform APIs, do not use `ssize_t`. MSVC lacks it, and
86prefer out-of-band error signaling for `size_t` (see Return values).
87
88
89## Naming
90
91Follow Google naming conventions in C++ files. In C files, use the
92following naming conventions for consistency with existing OpenSSL and C
93styles:
94
95Define structs with typedef named `TYPE_NAME`. The corresponding struct
96should be named `struct type_name_st`.
97
98Name public functions as `MODULE_function_name`, unless the module
99already uses a different naming scheme for legacy reasons. The module
100name should be a type name if the function is a method of a particular
101type.
102
103Some types are allocated within the library while others are initialized
104into a struct allocated by the caller, often on the stack. Name these
105functions `TYPE_NAME_new`/`TYPE_NAME_free` and
106`TYPE_NAME_init`/`TYPE_NAME_cleanup`, respectively. All `TYPE_NAME_free`
107functions must do nothing on `NULL` input.
108
109If a variable is the length of a pointer value, it has the suffix
110`_len`. An output parameter is named `out` or has an `out_` prefix. For
111instance, For instance:
112
113    uint8_t *out,
114    size_t *out_len,
115    const uint8_t *in,
116    size_t in_len,
117
118Name public headers like `include/openssl/evp.h` with header guards like
119`OPENSSL_HEADER_EVP_H`. Name internal headers like
120`crypto/ec/internal.h` with header guards like
121`OPENSSL_HEADER_EC_INTERNAL_H`.
122
123Name enums like `enum unix_hacker_t`. For instance:
124
125    enum should_free_handshake_buffer_t {
126      free_handshake_buffer,
127      dont_free_handshake_buffer,
128    };
129
130
131## Return values
132
133As even `malloc` may fail in BoringSSL, the vast majority of functions
134will have a failure case. Functions should return `int` with one on
135success and zero on error. Do not overload the return value to both
136signal success/failure and output an integer. For example:
137
138    OPENSSL_EXPORT int CBS_get_u16(CBS *cbs, uint16_t *out);
139
140If a function needs more than a true/false result code, define an enum
141rather than arbitrarily assigning meaning to int values.
142
143If a function outputs a pointer to an object on success and there are no
144other outputs, return the pointer directly and `NULL` on error.
145
146
147## Parameters
148
149Where not constrained by legacy code, parameter order should be:
150
1511. context parameters
1522. output parameters
1533. input parameters
154
155For example,
156
157    /* CBB_add_asn sets |*out_contents| to a |CBB| into which the contents of an
158     * ASN.1 object can be written. The |tag| argument will be used as the tag for
159     * the object. It returns one on success or zero on error. */
160    OPENSSL_EXPORT int CBB_add_asn1(CBB *cbb, CBB *out_contents, uint8_t tag);
161
162
163## Documentation
164
165All public symbols must have a documentation comment in their header
166file. The style is based on that of Go. The first sentence begins with
167the symbol name, optionally prefixed with "A" or "An". Apart from the
168initial mention of symbol, references to other symbols or parameter
169names should be surrounded by |pipes|.
170
171Documentation should be concise but completely describe the exposed
172behavior of the function. Pay special note to success/failure behaviors
173and caller obligations on object lifetimes. If this sacrifices
174conciseness, consider simplifying the function's behavior.
175
176    /* EVP_DigestVerifyUpdate appends |len| bytes from |data| to the data which
177     * will be verified by |EVP_DigestVerifyFinal|. It returns one on success and
178     * zero otherwise. */
179    OPENSSL_EXPORT int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *data,
180                                              size_t len);
181
182Explicitly mention any surprising edge cases or deviations from common
183return value patterns in legacy functions.
184
185    /* RSA_private_encrypt encrypts |flen| bytes from |from| with the private key in
186     * |rsa| and writes the encrypted data to |to|. The |to| buffer must have at
187     * least |RSA_size| bytes of space. It returns the number of bytes written, or
188     * -1 on error. The |padding| argument must be one of the |RSA_*_PADDING|
189     * values. If in doubt, |RSA_PKCS1_PADDING| is the most common.
190     *
191     * WARNING: this function is dangerous because it breaks the usual return value
192     * convention. Use |RSA_sign_raw| instead. */
193    OPENSSL_EXPORT int RSA_private_encrypt(int flen, const uint8_t *from,
194                                           uint8_t *to, RSA *rsa, int padding);
195
196Document private functions in their `internal.h` header or, if static,
197where defined.
198