|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198 |
- BoringSSL Style Guide.
-
- BoringSSL usually follows the Google C++ style guide, found below. The
- rest of this document describes differences and clarifications on top
- of the base guide.
-
- https://google-styleguide.googlecode.com/svn/trunk/cppguide.html
-
-
- Legacy code.
-
- As a derivative of OpenSSL, BoringSSL contains a lot of legacy code
- that does not follow this style guide. Particularly where public API
- is concerned, balance consistency within a module with the benefits of
- a given rule. Module-wide deviations on naming should be respected
- while integer and return value conventions take precedence over
- consistency.
-
- Some modules have seen few changes, so they still retain the original
- indentation style for now. When editing these, try to retain the
- original style. For Emacs, doc/c-indentation.el from OpenSSL may be
- helpful in this.
-
-
- Language.
-
- The majority of the project is in C, so C++-specific rules in the
- Google style guide do not apply. Support for C99 features depends on
- our target platforms. Typically, Chromium's target MSVC is the most
- restrictive.
-
- Variable declarations in the middle of a function are allowed.
-
- Comments should be /* C-style */ for consistency.
-
- When declaration pointer types, * should be placed next to the variable
- name, not the type. So
-
- uint8_t *ptr;
-
- not
-
- uint8_t* ptr;
-
- Rather than malloc() and free(), use the wrappers OPENSSL_malloc() and
- OPENSSL_free(). Use the standard C assert() function freely.
-
- For new constants, prefer enums when the values are sequential and typed
- constants for flags. If adding values to an existing set of #defines, continue
- with #define.
-
-
- Formatting.
-
- Single-statement blocks are not allowed. All conditions and loops must
- use braces:
-
- if (foo) {
- do_something();
- }
-
- not
-
- if (foo)
- do_something();
-
-
- Integers.
-
- Prefer using explicitly-sized integers where appropriate rather than
- generic C ones. For instance, to represent a byte, use uint8_t, not
- unsigned char. Likewise, represent a two-byte field as uint16_t, not
- unsigned short.
-
- Sizes are represented as size_t.
-
- Within a struct that is retained across the lifetime of an SSL
- connection, if bounds of a size are known and it's easy, use a smaller
- integer type like uint8_t. This is a "free" connection footprint
- optimization for servers. Don't make code significantly more complex
- for it, and do still check the bounds when passing in and out of the
- struct. This narrowing should not propagate to local variables and
- function parameters.
-
- When doing arithmetic, account for overflow conditions.
-
- Except with platform APIs, do not use ssize_t. MSVC lacks it, and
- prefer out-of-band error signaling for size_t (see Return values).
-
-
- Naming.
-
- Follow Google naming conventions in C++ files. In C files, use the
- following naming conventions for consistency with existing OpenSSL and C
- styles:
-
- Define structs with typedef named TYPE_NAME. The corresponding struct
- should be named struct type_name_st.
-
- Name public functions as MODULE_function_name, unless the module
- already uses a different naming scheme for legacy reasons. The module
- name should be a type name if the function is a method of a particular
- type.
-
- Some types are allocated within the library while others are
- initialized into a struct allocated by the caller, often on the
- stack. Name these functions TYPE_NAME_new/TYPE_NAME_free and
- TYPE_NAME_init/TYPE_NAME_cleanup, respectively. All TYPE_NAME_free
- functions must do nothing on NULL input.
-
- If a variable is the length of a pointer value, it has the suffix
- _len. An output parameter is named out or has an out_ prefix. For
- instance, For instance:
-
- uint8_t *out,
- size_t *out_len,
- const uint8_t *in,
- size_t in_len,
-
- Name public headers like include/openssl/evp.h with header guards like
- OPENSSL_HEADER_EVP_H. Name internal headers like crypto/ec/internal.h
- with header guards like OPENSSL_HEADER_EC_INTERNAL_H.
-
- Name enums like unix_hacker_t. For instance:
-
- enum should_free_handshake_buffer_t {
- free_handshake_buffer,
- dont_free_handshake_buffer,
- };
-
-
- Return values.
-
- As even malloc may fail in BoringSSL, the vast majority of functions
- will have a failure case. Functions should return int with one on
- success and zero on error. Do not overload the return value to both
- signal success/failure and output an integer. For example:
-
- OPENSSL_EXPORT int CBS_get_u16(CBS *cbs, uint16_t *out);
-
- If a function needs more than a true/false result code, define an enum
- rather than arbitrarily assigning meaning to int values.
-
- If a function outputs a pointer to an object on success and there are no
- other outputs, return the pointer directly and NULL on error.
-
-
- Parameters.
-
- Where not constrained by legacy code, parameter order should be:
-
- 1. context parameters
- 2. output parameters
- 3. input parameters
-
- For example,
-
- /* CBB_add_asn sets |*out_contents| to a |CBB| into which the contents of an
- * ASN.1 object can be written. The |tag| argument will be used as the tag for
- * the object. It returns one on success or zero on error. */
- OPENSSL_EXPORT int CBB_add_asn1(CBB *cbb, CBB *out_contents, uint8_t tag);
-
-
- Documentation.
-
- All public symbols must have a documentation comment in their header
- file. The style is based on that of Go. The first sentence begins with
- the symbol name, optionally prefixed with "A" or "An". Apart from the
- initial mention of symbol, references to other symbols or parameter
- names should be surrounded by |pipes|.
-
- Documentation should be concise but completely describe the exposed
- behavior of the function. Pay special note to success/failure behaviors
- and caller obligations on object lifetimes. If this sacrifices
- conciseness, consider simplifying the function's behavior.
-
- /* EVP_DigestVerifyUpdate appends |len| bytes from |data| to the data which
- * will be verified by |EVP_DigestVerifyFinal|. It returns one on success and
- * zero otherwise. */
- OPENSSL_EXPORT int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *data,
- size_t len);
-
- Explicitly mention any surprising edge cases or deviations from common
- return value patterns in legacy functions.
-
- /* RSA_private_encrypt encrypts |flen| bytes from |from| with the private key in
- * |rsa| and writes the encrypted data to |to|. The |to| buffer must have at
- * least |RSA_size| bytes of space. It returns the number of bytes written, or
- * -1 on error. The |padding| argument must be one of the |RSA_*_PADDING|
- * values. If in doubt, |RSA_PKCS1_PADDING| is the most common.
- *
- * WARNING: this function is dangerous because it breaks the usual return value
- * convention. Use |RSA_sign_raw| instead. */
- OPENSSL_EXPORT int RSA_private_encrypt(int flen, const uint8_t *from,
- uint8_t *to, RSA *rsa, int padding);
-
- Document private functions in their internal.h header or, if static,
- where defined.
|