New code in OpenSSL is expected to follow the conventions in this guide. Existing code does not uniformly comply and is being brought up to standard gradually; non-trivial changes to existing code should bring the affected area into compliance.
When bringing an area into compliance as part of a larger change, do so in a separate commit -- typically one that lands first, so that the substantive change then operates on already-compliant code. Combining a compliance sweep with a behaviour change in one commit makes the diff hard to review and hard to revert.
Do not bring code into compliance as part of a bug fix. Make the minimal change that fixes the bug. This holds for any bug fix, and especially for one that may be backported to a stable release branch -- and at the time of the fix you often cannot know whether it will be. Mixing compliance changes into a fix complicates backporting and makes the change larger than it needs to be. Leave any compliance work for a separate change.
The language is C99 (ISO/IEC 9899:1999). More modern C versions are not yet supported on every platform OpenSSL targets and should be avoided.
OpenSSL follows the WebKit coding style for C code. In cases where the WebKit guide gives different rules for C and C++, OpenSSL uses the C variant.
Whitespace, indentation, brace placement, line wrapping, alignment and
the other mechanical aspects of formatting are enforced by clang-format
using the .clang-format file at the top of this
repository. The configuration is the WebKit C style with a small set
of OpenSSL-specific customisations (notably the list of project
typedefs, the STACK_OF / LHASH_OF type macros, and the list of
statement-shaped macros).
Run clang-format on your changes before submitting; the output of
clang-format is deemed correct. See
CONTRIBUTING.md for the tooling (.pre-commit-config.yaml,
the util/reformat-patches.sh helper, and editor integrations).
In rare situations it may be necessary to disable clang-format on a
piece of code. This may be done with paired comments:
/* clang-format off */
I am doing something nasty here.
Reviewers should be triggered.
/* clang-format on */This should be used sparingly, and should not be used if there is any other way to do what you are doing.
Multi-line comment blocks have an additional clang-format opt-out
via the /** and /*- markers; see Comments.
A name describes what the identifier holds or what it does.
Match the name to its role: a variable holding an X509 * is
typically cert; one holding an X509_STORE_CTX * is typically
ctx; a function that counts the number of active users is
called count_active_users(), not cntusr(). Use whole words
when there is no established short form, and reuse the same
name across the codebase for the same concept rather than
inventing synonyms.
Names use lowercase with underscores (snake_case). For public functions, snake_case applies to the portion of the name after the uppercase subsystem prefix (see below). Do not begin a name with an underscore; identifiers starting with an underscore are reserved by the C standard in various contexts and can collide with toolchain or system identifiers.
For variables, OpenSSL has well-established short forms that
are fine to use without further qualification: ctx, ptr,
len, buf, cert, key, pkey, ret, tmp, and similar.
Use these in preference to longer forms; do not coin a new
variant when one of these already covers the meaning. Use the
suffix _count for a number of items, _len for a byte length,
and _size for a size in bytes; do not invent variants like
num_X, X_length, or X_bytes when one of these already
applies.
A variable that mirrors notation from a standard, RFC, paper,
or other authoritative specification being implemented may use
whatever name the spec uses (for example, n, e, d for RSA
parameters, or salt and info for HKDF). Document the spec
citation and which variables come from it in the function or
file doxygen comment; see Doxygen comments
for the form.
Outside spec-mirroring, single letters are appropriate only as
loop counters (i, j, k).
For functions, OpenSSL names follow a PREFIX_[OBJECT_]action()
shape: an uppercase subsystem prefix; then, where the function
operates on a particular object or context, that object -- usually
the uppercase or mixed-case type name; then the action, in
lowercase with underscores. Where the prefix already identifies
the object, or the function is a general subsystem utility, there
is no separate object element.
Examples: EVP_KDF_CTX_get0_kdf (prefix EVP, object KDF_CTX,
action get0_kdf), EVP_PKEY_sign, OSSL_CMP_validate_msg,
SSL_CTX_set_verify; and, with no object element, BIO_eof and
CRYPTO_malloc.
This shape is aspirational and describes the direction for new code. Much of the existing API predates it and carries years of naming baggage, so it does not uniformly conform. Do not rename existing public functions to fit it -- that breaks the API.
Public (API) functions use the uppercase subsystem prefix.
Internal functions use the lowercase ossl_ prefix unless they
are static (i.e., local to the source file); static functions
need no prefix.
Functions that return a pointer disclose ownership of the
returned value via a 0 or 1 suffix on the name:
get0_X()returns a non-owning pointer.get1_X()returns an owning pointer; the caller is the new owner, of either a fresh allocation or an up-ref.
The same convention applies in reverse for setters and pushers that take a pointer:
set0_X(obj, p)andpush0_X(coll, p)transfer ownership ofptoobjorcoll.set1_X(obj, p)andpush1_X(coll, p)leave ownership with the caller; the callee stores a copy or up-ref.
Use these forms rather than a bare get_ / set_ / push_
whenever a pointer crosses the API boundary.
A function extended from an existing form takes an _ex
suffix (_ex2 for a second extension, _ex3 for a third,
and so on). See Extending existing functions
for when to add an extended form and how to handle the
parameter list.
OpenSSL uses typedefs extensively. Struct typedefs are named in
ALL_CAPS_WITH_UNDERSCORES, with a subsystem prefix, and the
underlying struct tag is the lowercase form of the typedef name
suffixed _st:
typedef struct evp_pkey_st EVP_PKEY;For more examples, look in <openssl/types.h>.
When a typedef'd enum is used (see Structs and typedefs below for the policy on enums), the enum type name is lowercase and the values are uppercase.
Function-pointer and callback typedefs use one of two suffixes:
_cbfor typedefs that are user-supplied callbacks (X509_STORE_CTX_verify_cb,pem_password_cb)._fnfor function pointers in an internal interface or dispatch table (OSSL_provider_init_fn,X509_STORE_CTX_verify_fn).
When introducing a new type, consider that a bare or generic
name may collide with system or third-party headers; OpenSSL
has historically used unprefixed names like X509 and these
now collide with Windows headers in places. Prefix new type
names (for example EVP_PKEY, OSSL_PARAM) to avoid this.
Macros and labels in enums should be named in
ALL_CAPS_WITH_UNDERSCORES. This convention helps distinguish
macros from functions and variables.
#define OPENSSL_MAGIC_FOO 0x12345Error reason codes follow a SUBSYSTEM_R_REASON pattern,
where _R_ is the infix marking the macro as an error reason:
X509_R_INVALID_TRUST, SSL_R_NO_SHARED_CIPHER,
ERR_R_MALLOC_FAILURE.
Feature-disable macros follow OPENSSL_NO_<FEATURE> -- for
example, OPENSSL_NO_SOCK (no socket support),
OPENSSL_NO_RSA (no RSA), OPENSSL_NO_DEPRECATED_<MAJOR>_<MINOR>
(no APIs deprecated as of that version). When defined, the
corresponding feature's headers and implementations are
conditionally compiled out.
This section describes the form and style of code comments. DOCUMENTATION.md is the companion document that describes the policy: when a comment is required, the trivial exception, and the per-field commenting requirement on structures.
Use the classic /* ... */ comment markers. Do not use // ...
markers.
Comments should describe what the code does and why. Do not parrot the effect of each statement; well-written code is its own description of how. As the complexity of the code increases, the size and detail of comments should also increase. Err in favour of more comments rather than fewer: code that is obvious to you today will not necessarily be obvious to someone else two years later.
The preferred style for long (multi-line) comments is:
/*-
* This is the preferred style for multi-line
* comments in the OpenSSL source code.
* Please use it consistently.
*
* Description: A column of asterisks on the left side,
* with beginning and ending almost-blank lines.
*/Both /*- and /** are recognised by the CommentPragmas setting
in .clang-format and cause the block to be left
exactly as written. Use /*- for plain prose comments whose layout
you want to preserve, and /** for doxygen blocks (see below).
Use /* TODO: <short description> */ to mark work that should be
done later. Use /* FIXME: <short description> */ to mark a known
incorrectness, hack, or workaround that needs to be addressed. If
a marker is worth adding, the underlying work is worth tracking:
ensure a GitHub issue is opened for it and include the issue's
full URL in the marker (e.g., /* TODO: <short description> (https://github.com/openssl/openssl/issues/1234) */). Use the URL
form because OpenSSL has issue trackers in multiple repositories.
OpenSSL code uses doxygen-style comments on functions, data structures, and macros to make the source easier to navigate and to translate into reference documentation. The internal-function, struct-field, and other in-source documentation requirements set out in DOCUMENTATION.md must be satisfied with doxygen-style comments using the conventions described below.
Use the @ form of doxygen markers (@brief, @param, @returns,
@file, @def, @struct, and so on). Do not use the \ form
(\brief, \param, etc.).
For the full set of recognised tags and their semantics, see the Doxygen manual: the commands list is the practical reference for what you can write inside a doxygen block; the chapter on documenting the code explains the block forms and where comments attach.
The following sample illustrates the convention:
/**
* @file doxysample.c
* This is a brief file description that you may add.
* Subsequent lines contain more detailed information about what you
* will find defined in this file. It is not currently required that
* you add a file description, but it is available if you like.
*/
/**
* @def MAX(x, y)
* Document a macro that returns the maximum of two inputs.
* @param x integer input value
* @param y integer input value
* @returns the maximum of x and y
*/
#define MAX(x, y) ((x) > (y) ? (x) : (y))
/**
* @struct foo_st
* @brief Description of the foo_st struct.
* Optional more detailed description here.
*/
typedef struct foo_st {
int a; /**< Describe the a field here */
char b; /**< Describe the b field here */
} FOO;
/**
* @brief Describe the function ossl_add briefly.
* Add a more detailed description here, like sums two inputs and
* returns the result.
* @param a input integer to add
* @param b input integer to add
* @returns the sum of a and b
*/
int ossl_add(int a, int b);When a function uses variable names taken from a specification (see Functions and variables in the Naming section), the doxygen block cites the spec and identifies each spec-derived variable:
/**
* @brief Transmogrify Calvin into Hobbes per RFC 31337 section 1.2.3.
*
* Variable naming follows the spec:
* - Calvin: input to be transmogrified
* - Hobbes: transmogrified output (caller-allocated)
*
* @param Calvin pointer to the input bytes to transmogrify
* @param Calvin_len the number of bytes available at Calvin
* @param Hobbes pointer to the caller-allocated output buffer
* @param Hobbes_len the number of bytes available at Hobbes
* @returns 1 on success, 0 on failure
* @see https://www.example.org/rfc/rfc31337.html#section-1.2.3
* @see https://calvinandhobbes.fandom.com/wiki/Transmogrifier
*/
int ossl_transmogrify(const uint8_t *Calvin, size_t Calvin_len,
uint8_t *Hobbes, size_t Hobbes_len);Every public function declaration in a public header must carry a
doxygen block that includes an @see referencing the function's
manual page in the standard name(3) form. This in-source comment
is a navigation aid; the canonical reference documentation lives in
the POD file under doc/man3/ (see DOCUMENTATION.md).
The cross-reference is to the function name, not the POD file
name; the build emits a man-page entry per function name, so
man X509_verify_cert resolves regardless of which POD file
currently documents it.
/**
* @brief One-line summary of what the function does.
* @see X509_verify_cert(3)
*/
int X509_verify_cert(X509_STORE_CTX *ctx);Additional @see entries may be added for any manual page a caller
needs in order to use the function correctly, such as pages
documenting argument types, the flag families that affect the
function's behaviour, or closely related functions. List them
comma-separated on a single @see, matching the form used in POD's
SEE ALSO section:
/**
* @brief One-line summary of what the function does.
* @see X509_verify_cert(3), X509_STORE_CTX_new(3),
* X509_VERIFY_PARAM_set_flags(3)
*/
int X509_verify_cert(X509_STORE_CTX *ctx);The doxygen comment should not duplicate the POD content. Two
copies of "what this function does" inevitably diverge; the POD is
the source of truth. Keep the doxygen block to a short summary and
the @see references.
See Typedefs under Naming for naming conventions.
Typedef'd enums are used much less often than struct typedefs; consider not using a typedef for an enum at all. A typedef'd enum hides the integer-ness of the type from the caller, which makes the implementation-defined underlying type easier to forget.
Enum arguments to public functions are not permitted. C's enum
underlying type is implementation-defined, and adding values to
an enum can change its ABI; use int and document the allowed
values instead.
OpenSSL has historically made all struct definitions public, which caused problems with maintaining binary compatibility and adding features. New structs are opaque and expose only pointers in the API; the struct definition is placed in a local header file that is not exported. Legacy structs that are still part of the public ABI are exempt; do not add new public struct definitions.
In practice, the opaque pattern is to forward-declare the typedef
in the public header (typedef struct foo_st FOO;, with no struct
body) and place the struct foo_st { ... }; definition in a local
header that is not exported. Callers see only the pointer type.
Bitfield layout is implementation-defined and varies across compilers and ABIs. Where that layout is observable -- in structs that are part of the public ABI or that mirror a wire or file format -- avoid bitfields and use explicit shifts and masks on a regular integer instead.
Flexible array members (C99 trailing []) are permitted and
preferred over the older [1] "struct hack" for variable-length
trailing data. Remember that sizeof(struct) does not include the
flexible member; allocate the trailing data explicitly when the
struct is created.
C99 designated initializers ({ .field = value }) are encouraged
for struct initialisation, particularly where they make the field
assignments self-documenting.
A trailing comma in an initializer list is a layout hint to
clang-format: with it the list is kept one element per line;
without it the formatter may pack the list onto fewer lines.
Most of the time you do not want a trailing comma; omit it
unless you specifically want to lock the one-per-line layout
(for example, in a multi-row table of values).
Prefer explicitly-sized integers over generic C ones where the
size matters. To represent a byte use uint8_t, not
unsigned char; for a two-byte field, uint16_t rather than
unsigned short.
Avoid long and long long specifically. long is 32 bits on
64-bit Windows and 64 bits on 64-bit Linux; using it for "at
least 32 bits" produces code that works inconsistently across
platforms. Use int32_t, int64_t, size_t, or another
<stdint.h> type as appropriate.
Sizes are size_t. When converting to or from int for legacy
reasons, check for overflow and underflow.
Add an integer literal suffix when the literal participates in a
shift or appears in an expression involving a wider type --
without a suffix the literal is int. Use U for unsigned
semantics (1U << 31) and the UINT8_C through UINT64_C
macros from <stdint.h> for explicit widths (UINT32_C(1) << 31,
UINT64_C(1) << 63). Avoid UL and ULL, for the same reason
as long / long long: their widths vary by platform.
Bit shifts should be performed on unsigned operands.
Left-shifting a signed value is undefined behaviour when the
operand is negative or when the result reaches the sign bit;
right-shifting a signed negative value is implementation-defined.
Combined with the literal-suffix rule above, shifts of constants
typically take the form UINT32_C(1) << n or (uint32_t)x << n.
In structs that are retained across the lifetime of a connection,
new integer fields whose value range is known should use a smaller
integer type (uint8_t, uint16_t) where doing so is
straightforward. This reduces per-connection memory in server
processes. Do not make code significantly more complex to achieve
it, and continue to bounds-check at the struct boundary.
This narrowing should not propagate to local variables or function parameters; those use the conventional integer types so callers are not forced to deal with narrow types.
Do not retroactively narrow existing integer fields in legacy structs; this risks ABI breakage.
When doing arithmetic, account for overflow.
Use int with 0 / 1 for boolean values, both in public API
and internal code. Do not introduce <stdbool.h> for new code;
the public API convention is int, and using bool internally
just to convert to int at the API boundary adds friction
without enough benefit.
Except in platform-specific code, do not use ssize_t; MSVC lacks
it. Use size_t and signal errors out-of-band (see
Return values in new code).
Headers use traditional include guards in the #if defined()
form rather than #pragma once, which is non-standard:
#if !defined(OPENSSL_FOO_H)
#define OPENSSL_FOO_H
/* ... header contents ... */
#endif /* defined(OPENSSL_FOO_H) */Prefer #if defined(FOO) and #if !defined(FOO) to #ifdef and
#ifndef. This allows logical operations when conditional
compilation is dependent on more than one variable, without
nesting multiple blocks.
All #endif blocks must have a comment matching their #if:
#if defined(OPENSSL_LINUX) && (!defined(OPENSSL_NO_HOOBLA) || !defined(OPENSSL_BULA))
...
#endif /* defined(OPENSSL_LINUX) && (!defined(OPENSSL_NO_HOOBLA) || !defined(OPENSSL_BULA)) */Minimise the footprint of conditional compilation in source code: the more conditional code is concentrated and confined, the easier the unconditional flow is to read.
Concentrate conditional compilation rather than dispersing it. Do not duplicate the same OS-dispatch ladder across the codebase:
#if defined(OPENSSL_OS_FOO) || defined(OPENSSL_OS_BAR)
stuff the way foo or bar does it;
#elif defined(OPENSSL_OS_BLAH) || defined(OPENSSL_OS_WOOF)
stuff the way blah or woof does it;
#endif /* defined(OPENSSL_OS_FOO) || defined(OPENSSL_OS_BAR) */For OS-dependent code in particular, put the directives inside
a single function that wraps the OS-dependent work, so callers
see a clean interface. When the OS-dependent implementations
are large, put them in separate files (stuff_foo.c,
stuff_blah.c) implementing a common function and select the
appropriate file via the build process; this lets non-mainstream
platforms add an implementation file without patching shared
code.
When a feature can be compiled out, prefer to provide a no-op
stub implementation of its functions in the disabled case
rather than wrapping every call site in #if. Callers then
invoke the functions unconditionally and the compiler discards
the stubs:
#if defined(OPENSSL_NO_FOO)
static ossl_inline int ossl_foo_init(void) { return 1; }
static ossl_inline void ossl_foo_cleanup(void) { }
#else
int ossl_foo_init(void);
void ossl_foo_cleanup(void);
#endif /* defined(OPENSSL_NO_FOO) */Just use a function, not a macro. OpenSSL has historically used macros heavily to avoid function-call overhead, but modern compilers inline well; the trade-offs that justified that pattern no longer apply. Where a macro is genuinely unavoidable, the rules below apply.
For the naming convention used for macros and enum labels, see the Macros and enum labels subsection of Naming above.
Enums are preferred when defining several related constants.
Enum arguments to public functions are not permitted, because
C's enum underlying type is implementation-defined and adding
values can change ABI; see
Structs and typedefs for the rule and
the canonical alternative (use int and document the allowed
values).
Where the constants need a fixed underlying width (for ABI or
wire-format reasons), use #define or static const with an
explicit-width type from <stdint.h> instead, since enum width
is implementation-defined.
Avoid complex or clever macros: they are hard to read, debug, and maintain. Do not nest macros calling other macros.
Prefer functions over function-like macros. Do not optimise for
function-call overhead without first measuring with a function
implementation; if the function is hot enough to need inlining,
mark it ossl_inline rather than converting it to a macro.
Always parenthesise arguments in function-like macros to prevent operator-precedence issues during expansion. Enclose the entire macro definition in parentheses if it expands to an expression, so the expansion evaluates correctly inside larger expressions. For example:
#define BOB(blah) ((blah) + 42 - 23)Enclose multi-statement macros in a do { } while (0) block. Do
not include a semicolon at the end, and do not use bare braces
(which fail when followed by else). For example:
/* This is bad. */
#define KERMIT(x) muppet((x)); frog((x)); green((x))
if (something)
KERMIT(bob);
else /* This now breaks. */
/* This is also bad, because now you have to omit the semicolon. */
#define KERMIT(x) { muppet((x)); frog((x)); green((x)) }
if (something)
KERMIT(bob) /* No semicolon. */
else
/* This works. */
#define KERMIT(x) do { muppet((x)); frog((x)); green((x)) } while (0)
if (something)
KERMIT(bob);
else
/*
* But just use a function -- now we know that x is an integer that
* has something to do with frogginess and we gain some type safety.
*/
static void kermit(int frogginess)
{
muppet(frogginess);
frog(frogginess);
green(frogginess);
}
if (something)
kermit(bob);
elseDo not put code in a file and include it inline:
...
printf("Yolo\n");
#include "./abagfullofcode.inc"
printf("That was fun\n");
...Either make a function out of the code and call it, or put the code in place.
Be careful when writing a function-like macro that could be called
with arguments that have side effects. Because a macro may expand an
argument more than once, a side-effecting argument (n++, a function
call, a volatile access) can then be evaluated more than once, with
unexpected results:
#define SQUARE(x) ((x) * (x))
int n = 1;
int result = SQUARE(n++); /* expands to ((n++) * (n++)) -- evaluates twice */Where it can reasonably be avoided, prefer a form that expands each
argument exactly once -- a function, or an ossl_inline function
for a fixed type. If there is any doubt that your function-like
macro could be called with arguments that have side effects, treat
that as a sign to follow the advice in
Avoid function-like macros and make
it a real function. Some macros cannot avoid it: a type-generic macro
such as MAX must name each operand and so evaluates it more than
once. When that is unavoidable, say so at the definition and avoid
passing side-effecting expressions at the call site.
Do not write macros that rely on a particular variable name being in scope at the call site:
#define FOO(val) bar(index, (val)) /* requires `index' to exist */This is confusing to the reader and prone to breakage from seemingly innocent changes.
Do not write a macro that expands to something assignable:
#define FIELD(p) (((struct foo *)(p))->field)
FIELD(x) = y; /* legal C, but the macro hides the assignment */Use an accessor function or expose the field directly through a typed pointer.
Do not write macros that return, goto, break, or continue
out of their expansion. Such macros hide control flow from a
reader at the call site, who sees what looks like a function
call but which may exit the surrounding function or jump out of
a loop:
#define RETURN_IF_NULL(p) do { if ((p) == NULL) return -1; } while (0)
int ossl_frobnicate(void *p)
{
RETURN_IF_NULL(p); /* may return from ossl_frobnicate() -- not visible at the call site */
/* ... */
}The stringification (#) and token-pasting (##) operators are
forbidden in new code. Existing macros that use them (notably the
DECLARE_* and IMPLEMENT_* macro families) are not retroactively
changed; new code should achieve the same effect through
functions.
Variadic macros (__VA_ARGS__) are permitted but should be used
sparingly: prefer a function or a small set of helper functions
where possible. They are harder to reason about and debug than
functions, and the rules around zero variadic arguments and
__VA_ARGS__ forwarding are subtle.
A function should do one thing and be short enough that a reader can hold its behaviour in their head while reading it. Length follows from complexity, not the other way around: a long but flat function (for example, a single switch dispatching to many cases) is fine; a short function with three levels of nested control flow is not.
When complexity grows, factor out helpers with descriptive
names. A large number of local variables is a signal that this
factoring is overdue; consider splitting before reaching for a
comment to explain the variables. Performance-critical helpers
can be marked inline; see
Avoid function-like macros for
why this is preferable to a macro.
In function prototypes, include parameter names alongside their types. C does not require this, but it carries useful information for the reader; the name in the prototype should match the name in the definition.
A function that takes no arguments must declare so explicitly
with void in its parameter list: int f(void);, not
int f();. The latter declares the parameter list as
unspecified and prevents the compiler from checking calls.
Functions that are local to a single source file are declared
static. Static functions need no ossl_ prefix (see
Naming above) and do not appear in
the symbol table of the resulting object file.
In OpenSSL's API style, a context parameter (an SSL_CTX *,
EVP_PKEY_CTX *, OSSL_LIB_CTX *, or similar) is the first
parameter. The order of the remaining parameters is at the
function's discretion but should be consistent with similar
functions in the same subsystem.
Pointer parameters that are not modified by the function should
be declared const; likewise, pointer return values that the
caller must not modify should be declared const. The
return-side rule pairs with the get0_X() ownership convention:
a non-owning pointer is typically a read-only view, while an
owning pointer returned by get1_X() is non-const because the
caller controls it. The const qualifier documents the contract,
allows callers to pass or receive const-qualified data without
casts, and lets the compiler catch accidental modification.
Historically, functions in OpenSSL can return values of many different kinds, and one of the most common is a value indicating whether the function succeeded or failed. Usually this is:
1: success0: failure
Other patterns appear in legacy code:
-1indicates a serious error (internal error or memory allocation failure), and in some subsystems (BIO, SSL, etc.) means "should retry">= 1indicates success with the value carrying additional information;<= 0indicates failure with the value indicating the reason
Functions that return a computed value (not a success/failure indicator) are exempt.
Read the existing return-value contract carefully before modifying legacy code. OpenSSL's legacy return-value conventions are not uniform -- a function may use values, overloadings, or semantics outside the patterns above -- and bugs have been introduced into OpenSSL when contributors assumed a function followed a familiar pattern when it did not. The contract is part of the API, not just a stylistic choice.
For new code, functions should return int with 1 on success
and 0 on error. Do not overload the return value to both
signal success/failure and output an integer. For example:
/**
* @brief ossl_snuffle_thingamabob snuffles a thingamabob from bytes of input.
* If a valid thingamabob is snuffled, the result is stored in
* *out_thingamabob. On failure a snuffling error code is stored
* in *out_err.
* @param input pointer to the bytes to snuffle
* @param input_len the number of bytes available to snuffle from input
* @param out_err pointer to an integer to store an error code
* @param out_thingamabob pointer to a thingamabob to store the output
* @returns 1 if a thingamabob was snuffled and stored, 0 otherwise.
*/
int ossl_snuffle_thingamabob(const uint8_t *input, size_t input_len,
int *out_err, thingamabob *out_thingamabob);If a function outputs a single pointer and no other values,
return the pointer directly, with NULL on error.
A public function must verify that its arguments are sensible and return its documented failure value if they are not. Typical checks include:
- non-optional pointer arguments are not NULL;
- numeric arguments are within their expected ranges.
Public-API callers are outside the OpenSSL development envelope. The contract cannot be enforced through code review, so a NULL non-optional pointer or an out-of-range integer is a possibility that must be handled defensively at the boundary. Failing with a documented error code on the error stack is preferable to a SIGSEGV in the calling application's process.
For NULL pointer arguments, the canonical pattern is:
if (arg == NULL) {
ERR_raise(ERR_LIB_<lib>, ERR_R_PASSED_NULL_PARAMETER);
return 0;
}Use the function's documented failure value in place of 0
where it differs (NULL for pointer-returning functions, -1
for functions that may return -1, and so on).
Internal functions must not repeat these checks. Their callers
are us; the contract is enforceable in code review, and a NULL
or out-of-range argument is a programmer error of the same
character as the impossibilities discussed under
Assertions. A runtime check at an internal call
site is dead on any correct execution, and the untested branch
is itself attack surface. Use assert() instead where you want
to document an internal invariant.
When an existing public function needs additional parameters,
keep the original and add a new function with the same name plus
an _ex suffix (RAND_bytes_ex extends RAND_bytes). Further
extensions use _ex2, _ex3, and so on.
The extended function preserves the existing parameters in their existing order. New parameters may be inserted at any position (they do not have to be at the end); parameters that are no longer needed may be removed.
When a function exits from multiple locations and some common
work (such as cleanup) has to be done at every exit, use goto
to a single exit label. Return directly when there is no cleanup
to do. The rationale:
- a single exit point is easier to read and follow;
- it reduces excessive control structures and nesting;
- it avoids errors caused by failing to update multiple exit points when the code changes;
- it lets the compiler avoid emitting redundant cleanup code.
For example:
int ossl_do_thing(const uint8_t *in, size_t in_len)
{
int ret = 0;
uint8_t *buf = OPENSSL_malloc(in_len);
if (buf == NULL)
return 0;
if (!ossl_step1(in, in_len, buf))
goto out;
if (!ossl_step2(buf, in_len))
goto out;
ret = 1;
out:
OPENSSL_free(buf);
return ret;
}OpenSSL surfaces errors through a per-thread error stack; see
ERR_raise(3) for the calls and include/openssl/err.h for the
available reason codes. This section describes the conventions
for using them.
Raise at the leaf. The function that detects the failure pushes the error; intermediate wrappers that propagate the failure value must not re-raise. Re-raising on each frame floods the stack with duplicates and obscures the originating condition.
Use the ERR_LIB_<subsystem> corresponding to the function's
home directory (ERR_LIB_X509 in code under crypto/x509/, and
so on). Use a cross-library reason (ERR_R_PASSED_NULL_PARAMETER,
ERR_R_MALLOC_FAILURE, ERR_R_INTERNAL_ERROR, and others) for
portable failure modes; use a SUBSYSTEM_R_REASON
(X509_R_INVALID_TRUST, etc.) for domain-specific ones.
Do not call ERR_clear_error at function entry; the error stack
belongs to the caller, who may have pushed errors before
invoking you that they intend to inspect.
Use ERR_set_mark / ERR_pop_to_mark to suppress error-stack
pollution from operations expected to fail sometimes (a
speculative parse, a capability probe), leaving earlier errors
intact.
Use the OPENSSL_malloc family for general allocation; see
OPENSSL_malloc(3) for the full set of calls. Do not mix these
with the C standard library's malloc() / free() family;
allocations made with one set must be released with the matching
set, and OpenSSL can be built with custom allocator hooks that
the C library does not know about.
For arrays, use OPENSSL_malloc_array() and
OPENSSL_realloc_array(), which take the element size and
element count separately and check for integer overflow.
Memory holding sensitive material (key bytes, plaintext,
internal state of cryptographic primitives) must be cleansed
before release. OPENSSL_clear_free() combines cleansing and
freeing; OPENSSL_cleanse() wipes without freeing. For
long-lived sensitive data, use the OPENSSL_secure_malloc()
family (OPENSSL_secure_malloc(3)), which allocates from a
separate non-pageable secure heap, and release with
OPENSSL_secure_clear_free().
An API that owns internal state requires both an initialisation function to set it up and a completion function to release it. This is the standard constructor/destructor pair for opaque types; see Structs and typedefs.
The only reason for processor-specific code in OpenSSL is
performance. Every processor-specific path must have a
platform-neutral pure-C implementation as a fallback, because
not every target architecture or build configuration enables
the processor-specific path. OpenSSL selects between
implementations at runtime via the CPU-capability detection in
OPENSSL_cpuid_setup and the OPENSSL_* capability flags;
processor-specific code must integrate with this dispatch.
Cryptographic primitives operating on secret data must execute in time independent of those secrets. Avoid secret-dependent branches, secret-indexed memory accesses, and variable-time arithmetic (such as variable-time multiplication or division) on words derived from secrets. Hand-coded asm is sometimes used specifically to force a particular sequence of constant-time operations that a compiler might otherwise rewrite.
Short processor-specific operations are typically written as
inline assembly. Use a static inline function when the asm
constraints permit it. When the asm requires a compile-time
constant operand (an i constraint), use a statement-expression
macro instead, because a function parameter does not satisfy the
immediate-constant constraint. When asm() has side effects the
compiler cannot see, mark it volatile; do not mark volatile
unnecessarily as that limits optimisation.
When writing a single inline assembly statement containing
multiple instructions, put each instruction on a separate line
in a separate quoted string, and end each string except the
last with \n\t to properly indent the next instruction in the
assembly output:
asm("magic %reg1, #42\n\t"
"more_magic %reg2, %reg3"
: /* outputs */ : /* inputs */ : /* clobbers */);Large, non-trivial assembly functions go in pure assembly
modules, with corresponding C prototypes. The preferred way to
generate these is perlasm: a Perl script that generates a
.s file. Perlasm allows symbolic names for variables
(registers and stack-allocated locals) that are independent of
the specific assembler, and supports multiple ABIs and
assemblers from a single source by adhering to its coding
rules. See crypto/perlasm/x86_64-xlate.pl for an example.
Compiler intrinsics are permitted but used sparingly. They are
appropriate for self-contained SIMD acceleration where the
intrinsic vocabulary is well-supported across our target
compilers and the code does not need to span multiple ABIs --
crypto/evp/enc_b64_avx2.c (AVX2 base64) is an example.
Intrinsics are not appropriate for cryptographic primitives
where constant-time execution is required (the compiler may
reorder, branch, or otherwise alter the timing), or where an
existing perlasm implementation already covers the multi-ABI
case.
Assertions check programmer errors -- invariants, preconditions, and postconditions that must hold in any correctly-functioning build. They are not for runtime conditions such as allocation failure, I/O errors, or malformed input from callers; those are errors the surrounding code must handle and propagate.
OpenSSL provides three assertion forms, which differ in their
behaviour depending on whether NDEBUG is defined (release) or not
(debug):
| Form | Failure (debug) | Failure (release) | Success |
|---|---|---|---|
assert(e) |
abort | e not evaluated |
no effect |
ossl_assert(e) |
abort | returns 0 | returns 1 |
OPENSSL_assert(e) |
abort | abort | no effect |
Choosing between these forms is a trade-off, not a default. Each form pays a cost somewhere:
OPENSSL_assert()terminates the host process when an invariant fails, which is hostile to applications that link against OpenSSL.ossl_assert()returns failure in release builds so the host process survives, but the caller must then handle a failure for a condition that, by definition, cannot occur in correct code. That handling code is dead on any correct execution and cannot be exercised by ordinary tests; untested branches accumulate their own bugs and become part of the attack surface.assert()is silently dropped in release builds, so an invariant violation in production passes through to downstream code that may then operate on inconsistent state.
Use ossl_assert() when the surrounding function already returns
success/failure and the recovery path collapses naturally into the
function's existing error path: push an internal error and return
the function's failure value. The recovery code is then colocated
with tested error handling and is not a structurally new branch:
if (!ossl_assert(invariant_holds)) {
ERR_raise(ERR_LIB_..., ERR_R_INTERNAL_ERROR);
return 0;
}Use assert() for impossible cases in internal code -- typically
switch defaults, unreachable branches in helpers, and invariants
local to a function whose contract makes the violation strictly
impossible. The release-build behaviour ("do nothing") is the
right choice here, because the alternative is untested recovery
code for a case that cannot occur, and that code is itself a
hazard. The assertion expression must be free of side effects,
because assert() does not evaluate it in release builds.
Use OPENSSL_assert() only when continued execution would be more
dangerous than termination -- typically when global library state
is irrecoverably corrupted -- or in applications, test programs,
and fuzzers where termination on a failed check is desired.
OPENSSL_assert() aborts in all builds, including production.