nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 # BoringSSL Style Guide
2  
3 BoringSSL usually follows the
4 [Google C++ style guide](https://google.github.io/styleguide/cppguide.html),
5 The rest of this document describes differences and clarifications on
6 top of the base guide.
7  
8  
9 ## Legacy code
10  
11 As a derivative of OpenSSL, BoringSSL contains a lot of legacy code that
12 does not follow this style guide. Particularly where public API is
13 concerned, balance consistency within a module with the benefits of a
14 given rule. Module-wide deviations on naming should be respected while
15 integer and return value conventions take precedence over consistency.
16  
17 Some modules have seen few changes, so they still retain the original
18 indentation style for now. When editing these, try to retain the
19 original style. For Emacs, `doc/c-indentation.el` from OpenSSL may be
20 helpful in this.
21  
22  
23 ## Language
24  
25 The majority of the project is in C, so C++-specific rules in the
26 Google style guide do not apply. Support for C99 features depends on
27 our target platforms. Typically, Chromium's target MSVC is the most
28 restrictive.
29  
30 Variable declarations in the middle of a function are allowed.
31  
32 Comments should be `/* C-style */` for consistency.
33  
34 When declaration pointer types, `*` should be placed next to the variable
35 name, not the type. So
36  
37 uint8_t *ptr;
38  
39 not
40  
41 uint8_t* ptr;
42  
43 Rather than `malloc()` and `free()`, use the wrappers `OPENSSL_malloc()`
44 and `OPENSSL_free()`. Use the standard C `assert()` function freely.
45  
46 For new constants, prefer enums when the values are sequential and typed
47 constants for flags. If adding values to an existing set of `#define`s,
48 continue with `#define`.
49  
50  
51 ## Formatting
52  
53 Single-statement blocks are not allowed. All conditions and loops must
54 use braces:
55  
56 if (foo) {
57 do_something();
58 }
59  
60 not
61  
62 if (foo)
63 do_something();
64  
65  
66 ## Integers
67  
68 Prefer using explicitly-sized integers where appropriate rather than
69 generic 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  
73 Sizes are represented as `size_t`.
74  
75 Within a struct that is retained across the lifetime of an SSL
76 connection, if bounds of a size are known and it's easy, use a smaller
77 integer type like `uint8_t`. This is a "free" connection footprint
78 optimization for servers. Don't make code significantly more complex for
79 it, and do still check the bounds when passing in and out of the
80 struct. This narrowing should not propagate to local variables and
81 function parameters.
82  
83 When doing arithmetic, account for overflow conditions.
84  
85 Except with platform APIs, do not use `ssize_t`. MSVC lacks it, and
86 prefer out-of-band error signaling for `size_t` (see Return values).
87  
88  
89 ## Naming
90  
91 Follow Google naming conventions in C++ files. In C files, use the
92 following naming conventions for consistency with existing OpenSSL and C
93 styles:
94  
95 Define structs with typedef named `TYPE_NAME`. The corresponding struct
96 should be named `struct type_name_st`.
97  
98 Name public functions as `MODULE_function_name`, unless the module
99 already uses a different naming scheme for legacy reasons. The module
100 name should be a type name if the function is a method of a particular
101 type.
102  
103 Some types are allocated within the library while others are initialized
104 into a struct allocated by the caller, often on the stack. Name these
105 functions `TYPE_NAME_new`/`TYPE_NAME_free` and
106 `TYPE_NAME_init`/`TYPE_NAME_cleanup`, respectively. All `TYPE_NAME_free`
107 functions must do nothing on `NULL` input.
108  
109 If 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
111 instance, For instance:
112  
113 uint8_t *out,
114 size_t *out_len,
115 const uint8_t *in,
116 size_t in_len,
117  
118 Name 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  
123 Name 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  
133 As even `malloc` may fail in BoringSSL, the vast majority of functions
134 will have a failure case. Functions should return `int` with one on
135 success and zero on error. Do not overload the return value to both
136 signal success/failure and output an integer. For example:
137  
138 OPENSSL_EXPORT int CBS_get_u16(CBS *cbs, uint16_t *out);
139  
140 If a function needs more than a true/false result code, define an enum
141 rather than arbitrarily assigning meaning to int values.
142  
143 If a function outputs a pointer to an object on success and there are no
144 other outputs, return the pointer directly and `NULL` on error.
145  
146  
147 ## Parameters
148  
149 Where not constrained by legacy code, parameter order should be:
150  
151 1. context parameters
152 2. output parameters
153 3. input parameters
154  
155 For 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  
165 All public symbols must have a documentation comment in their header
166 file. The style is based on that of Go. The first sentence begins with
167 the symbol name, optionally prefixed with "A" or "An". Apart from the
168 initial mention of symbol, references to other symbols or parameter
169 names should be surrounded by |pipes|.
170  
171 Documentation should be concise but completely describe the exposed
172 behavior of the function. Pay special note to success/failure behaviors
173 and caller obligations on object lifetimes. If this sacrifices
174 conciseness, 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  
182 Explicitly mention any surprising edge cases or deviations from common
183 return 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  
196 Document private functions in their `internal.h` header or, if static,
197 where defined.