C9S/boringssl
2
0
Fork 0
mirror of https://boringssl.googlesource.com/boringssl synced 2026-07-21 14:43:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: Change |...| to ... for code references in comments 1/N

Browse Source 
This adds a Python script that executes a regex to modernize comment
style from enclosing code references in |pipes| to `backticks`. The
script outputs a list of remaining pipes in the file after doing all
replacements, and these are manually changed if necessary.

This CL includes the result of running the script over all public header
files in include/openssl whose filenames begin with a or b, and fixing
omissions manually if necessary.

Bug: 42290410
Change-Id: Id90ac8595cd6a64e3293b06f41c1d2416a6a6964
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/96107
Reviewed-by: David Benjamin <davidben@google.com>
Commit-Queue: Lily Chen <chlily@google.com>
This commit is contained in:
Lily Chen
2026-05-29 18:23:17 +00:00
committed by boringssl-scoped@luci-project-accounts.iam.gserviceaccount.com
parent aea2249834
commit d16fd05ba1
13 changed files with 1748 additions and 1662 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/openssl/aead.h
+153 -153
View File
@@ -29,22 +29,22 @@ extern "C" {
// message has a unique, per-message nonce and, optionally, additional data
// which is authenticated but not included in the ciphertext.
//
// The |EVP_AEAD_CTX_init| function initialises an |EVP_AEAD_CTX| structure and
// performs any precomputation needed to use |aead| with |key|. The length of
// the key, |key_len|, is given in bytes.
// The `EVP_AEAD_CTX_init` function initialises an `EVP_AEAD_CTX` structure and
// performs any precomputation needed to use `aead` with `key`. The length of
// the key, `key_len`, is given in bytes.
//
// The |tag_len| argument contains the length of the tags, in bytes, and allows
// The `tag_len` argument contains the length of the tags, in bytes, and allows
// for the processing of truncated authenticators. A zero value indicates that
// the default tag length should be used and this is defined as
// |EVP_AEAD_DEFAULT_TAG_LENGTH| in order to make the code clear. Using
// `EVP_AEAD_DEFAULT_TAG_LENGTH` in order to make the code clear. Using
// truncated tags increases an attacker's chance of creating a valid forgery.
// Be aware that the attacker's chance may increase more than exponentially as
// would naively be expected.
//
// When no longer needed, the initialised |EVP_AEAD_CTX| structure must be
// passed to |EVP_AEAD_CTX_cleanup|, which will deallocate any memory used.
// When no longer needed, the initialised `EVP_AEAD_CTX` structure must be
// passed to `EVP_AEAD_CTX_cleanup`, which will deallocate any memory used.
//
// With an |EVP_AEAD_CTX| in hand, one can seal and open messages. These
// With an `EVP_AEAD_CTX` in hand, one can seal and open messages. These
// operations are intended to meet the standard notions of privacy and
// authenticity for authenticated encryption. For formal definitions see
// Bellare and Namprempre, "Authenticated encryption: relations among notions
@@ -53,7 +53,7 @@ extern "C" {
// http://www-cse.ucsd.edu/~mihir/papers/oem.html.
//
// When sealing messages, a nonce must be given. The length of the nonce is
// fixed by the AEAD in use and is returned by |EVP_AEAD_nonce_length|. *The
// fixed by the AEAD in use and is returned by `EVP_AEAD_nonce_length`. *The
// nonce must be unique for all messages with the same key*. This is critically
// important - nonce reuse may completely undermine the security of the AEAD.
// Nonces may be predictable and public, so long as they are unique. Uniqueness
@@ -77,12 +77,12 @@ extern "C" {
// violated.
//
// The "seal" and "open" operations also permit additional data to be
// authenticated via the |ad| parameter. This data is not included in the
// authenticated via the `ad` parameter. This data is not included in the
// ciphertext and must be identical for both the "seal" and "open" call. This
// permits implicit context to be authenticated but may be empty if not needed.
//
// The "seal" and "open" operations may work in-place if the |out| and |in|
// arguments are equal. Otherwise, if |out| and |in| alias, input data may be
// The "seal" and "open" operations may work in-place if the `out` and `in`
// arguments are equal. Otherwise, if `out` and `in` alias, input data may be
// overwritten before it is read. This situation will cause an error.
//
// The "seal" and "open" operations return one on success and zero on error.
@@ -135,7 +135,7 @@ OPENSSL_EXPORT const EVP_AEAD *EVP_aead_xchacha20_poly1305(void);
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ctr_hmac_sha256(void);
// EVP_aead_aes_256_ctr_hmac_sha256 is AES-256 in CTR mode with HMAC-SHA256 for
// authentication. See |EVP_aead_aes_128_ctr_hmac_sha256| for details.
// authentication. See `EVP_aead_aes_128_ctr_hmac_sha256` for details.
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_ctr_hmac_sha256(void);
// EVP_aead_aes_128_gcm_siv is AES-128 in GCM-SIV mode. See RFC 8452.
@@ -200,20 +200,20 @@ OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_eax(void);
// Utility functions.
// EVP_AEAD_key_length returns the length, in bytes, of the keys used by
// |aead|.
// `aead`.
OPENSSL_EXPORT size_t EVP_AEAD_key_length(const EVP_AEAD *aead);
// EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce
// for |aead|.
// for `aead`.
OPENSSL_EXPORT size_t EVP_AEAD_nonce_length(const EVP_AEAD *aead);
// EVP_AEAD_max_overhead returns the maximum number of additional bytes added
// by the act of sealing data with |aead|.
// by the act of sealing data with `aead`.
OPENSSL_EXPORT size_t EVP_AEAD_max_overhead(const EVP_AEAD *aead);
// EVP_AEAD_max_tag_len returns the maximum tag length when using |aead|. This
// is the largest value that can be passed as |tag_len| to
// |EVP_AEAD_CTX_init|.
// EVP_AEAD_max_tag_len returns the maximum tag length when using `aead`. This
// is the largest value that can be passed as `tag_len` to
// `EVP_AEAD_CTX_init`.
OPENSSL_EXPORT size_t EVP_AEAD_max_tag_len(const EVP_AEAD *aead);
@@ -224,7 +224,7 @@ union evp_aead_ctx_st_state {
uint64_t alignment;
};
// An evp_aead_ctx_st (typedefed as |EVP_AEAD_CTX| in base.h) represents an AEAD
// An evp_aead_ctx_st (typedefed as `EVP_AEAD_CTX` in base.h) represents an AEAD
// algorithm configured with a specific key and message-independent IV.
struct evp_aead_ctx_st {
const EVP_AEAD *aead;
@@ -257,119 +257,119 @@ struct evp_aead_ctx_st {
// be used.
#define EVP_AEAD_DEFAULT_TAG_LENGTH 0
// EVP_AEAD_CTX_zero sets an uninitialized |ctx| to the zero state. It must be
// initialized with |EVP_AEAD_CTX_init| before use. It is safe, but not
// necessary, to call |EVP_AEAD_CTX_cleanup| in this state. This may be used for
// more uniform cleanup of |EVP_AEAD_CTX|.
// EVP_AEAD_CTX_zero sets an uninitialized `ctx` to the zero state. It must be
// initialized with `EVP_AEAD_CTX_init` before use. It is safe, but not
// necessary, to call `EVP_AEAD_CTX_cleanup` in this state. This may be used for
// more uniform cleanup of `EVP_AEAD_CTX`.
OPENSSL_EXPORT void EVP_AEAD_CTX_zero(EVP_AEAD_CTX *ctx);
// EVP_AEAD_CTX_new allocates an |EVP_AEAD_CTX|, calls |EVP_AEAD_CTX_init| and
// returns the |EVP_AEAD_CTX|, or NULL on error.
// EVP_AEAD_CTX_new allocates an `EVP_AEAD_CTX`, calls `EVP_AEAD_CTX_init` and
// returns the `EVP_AEAD_CTX`, or NULL on error.
OPENSSL_EXPORT EVP_AEAD_CTX *EVP_AEAD_CTX_new(const EVP_AEAD *aead,
const uint8_t *key,
size_t key_len, size_t tag_len);
// EVP_AEAD_CTX_free calls |EVP_AEAD_CTX_cleanup| and |OPENSSL_free| on
// |ctx|.
// EVP_AEAD_CTX_free calls `EVP_AEAD_CTX_cleanup` and `OPENSSL_free` on
// `ctx`.
OPENSSL_EXPORT void EVP_AEAD_CTX_free(EVP_AEAD_CTX *ctx);
// EVP_AEAD_CTX_init initializes |ctx| for the given AEAD algorithm. The |impl|
// EVP_AEAD_CTX_init initializes `ctx` for the given AEAD algorithm. The `impl`
// argument is ignored and should be NULL. Authentication tags may be truncated
// by passing a size as |tag_len|. A |tag_len| of zero indicates the default
// by passing a size as `tag_len`. A `tag_len` of zero indicates the default
// tag length and this is defined as EVP_AEAD_DEFAULT_TAG_LENGTH for
// readability.
//
// Returns 1 on success. Otherwise returns 0 and pushes to the error stack. In
// the error case, you do not need to call |EVP_AEAD_CTX_cleanup|, but it's
// the error case, you do not need to call `EVP_AEAD_CTX_cleanup`, but it's
// harmless to do so.
OPENSSL_EXPORT int EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead,
const uint8_t *key, size_t key_len,
size_t tag_len, ENGINE *impl);
// EVP_AEAD_CTX_cleanup frees any data allocated by |ctx|. It is a no-op to
// call |EVP_AEAD_CTX_cleanup| on a |EVP_AEAD_CTX| that has been |memset| to
// EVP_AEAD_CTX_cleanup frees any data allocated by `ctx`. It is a no-op to
// call `EVP_AEAD_CTX_cleanup` on a `EVP_AEAD_CTX` that has been `memset` to
// all zeros.
OPENSSL_EXPORT void EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx);
// EVP_AEAD_CTX_seal encrypts and authenticates |in_len| bytes from |in| and
// authenticates |ad_len| bytes from |ad| and writes the result to |out|. It
// EVP_AEAD_CTX_seal encrypts and authenticates `in_len` bytes from `in` and
// authenticates `ad_len` bytes from `ad` and writes the result to `out`. It
// returns one on success and zero otherwise.
//
// This function may be called concurrently with itself or any other seal/open
// function on the same |EVP_AEAD_CTX|.
// function on the same `EVP_AEAD_CTX`.
//
// At most |max_out_len| bytes are written to |out| and, in order to ensure
// success, |max_out_len| should be |in_len| plus the result of
// |EVP_AEAD_max_overhead|. On successful return, |*out_len| is set to the
// At most `max_out_len` bytes are written to `out` and, in order to ensure
// success, `max_out_len` should be `in_len` plus the result of
// `EVP_AEAD_max_overhead`. On successful return, `*out_len` is set to the
// actual number of bytes written.
//
// The length of |nonce|, |nonce_len|, must be equal to the result of
// |EVP_AEAD_nonce_length| for this AEAD.
// The length of `nonce`, `nonce_len`, must be equal to the result of
// `EVP_AEAD_nonce_length` for this AEAD.
//
// |EVP_AEAD_CTX_seal| never results in a partial output. If |max_out_len| is
// insufficient, zero will be returned. If any error occurs, |out| will be
// filled with zero bytes and |*out_len| set to zero.
// `EVP_AEAD_CTX_seal` never results in a partial output. If `max_out_len` is
// insufficient, zero will be returned. If any error occurs, `out` will be
// filled with zero bytes and `*out_len` set to zero.
//
// If |in| and |out| alias then |out| must be == |in|.
// If `in` and `out` alias then `out` must be == `in`.
OPENSSL_EXPORT int EVP_AEAD_CTX_seal(const EVP_AEAD_CTX *ctx, uint8_t *out,
size_t *out_len, size_t max_out_len,
const uint8_t *nonce, size_t nonce_len,
const uint8_t *in, size_t in_len,
const uint8_t *ad, size_t ad_len);
// EVP_AEAD_CTX_open authenticates |in_len| bytes from |in| and |ad_len| bytes
// from |ad| and decrypts at most |in_len| bytes into |out|. It returns one on
// EVP_AEAD_CTX_open authenticates `in_len` bytes from `in` and `ad_len` bytes
// from `ad` and decrypts at most `in_len` bytes into `out`. It returns one on
// success and zero otherwise.
//
// This function may be called concurrently with itself or any other seal/open
// function on the same |EVP_AEAD_CTX|.
// function on the same `EVP_AEAD_CTX`.
//
// At most |in_len| bytes are written to |out|. In order to ensure success,
// |max_out_len| should be at least |in_len|. On successful return, |*out_len|
// At most `in_len` bytes are written to `out`. In order to ensure success,
// `max_out_len` should be at least `in_len`. On successful return, `*out_len`
// is set to the the actual number of bytes written.
//
// The length of |nonce|, |nonce_len|, must be equal to the result of
// |EVP_AEAD_nonce_length| for this AEAD.
// The length of `nonce`, `nonce_len`, must be equal to the result of
// `EVP_AEAD_nonce_length` for this AEAD.
//
// |EVP_AEAD_CTX_open| never results in a partial output. If |max_out_len| is
// insufficient, zero will be returned. If any error occurs, |out| will be
// filled with zero bytes and |*out_len| set to zero.
// `EVP_AEAD_CTX_open` never results in a partial output. If `max_out_len` is
// insufficient, zero will be returned. If any error occurs, `out` will be
// filled with zero bytes and `*out_len` set to zero.
//
// If |in| and |out| alias then |out| must be == |in|.
// If `in` and `out` alias then `out` must be == `in`.
OPENSSL_EXPORT int EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx, uint8_t *out,
size_t *out_len, size_t max_out_len,
const uint8_t *nonce, size_t nonce_len,
const uint8_t *in, size_t in_len,
const uint8_t *ad, size_t ad_len);
// EVP_AEAD_CTX_seal_scatter encrypts and authenticates |in_len| bytes from |in|
// and authenticates |ad_len| bytes from |ad|. It writes |in_len| bytes of
// ciphertext to |out| and the authentication tag to |out_tag|. It returns one
// EVP_AEAD_CTX_seal_scatter encrypts and authenticates `in_len` bytes from `in`
// and authenticates `ad_len` bytes from `ad`. It writes `in_len` bytes of
// ciphertext to `out` and the authentication tag to `out_tag`. It returns one
// on success and zero otherwise.
//
// This function may be called concurrently with itself or any other seal/open
// function on the same |EVP_AEAD_CTX|.
// function on the same `EVP_AEAD_CTX`.
//
// Exactly |in_len| bytes are written to |out|, and up to
// |EVP_AEAD_max_overhead+extra_in_len| bytes to |out_tag|. On successful
// return, |*out_tag_len| is set to the actual number of bytes written to
// |out_tag|.
// Exactly `in_len` bytes are written to `out`, and up to
// `EVP_AEAD_max_overhead+extra_in_len` bytes to `out_tag`. On successful
// return, `*out_tag_len` is set to the actual number of bytes written to
// `out_tag`.
//
// |extra_in| may point to an additional plaintext input buffer if the cipher
// supports it. If present, |extra_in_len| additional bytes of plaintext are
// `extra_in` may point to an additional plaintext input buffer if the cipher
// supports it. If present, `extra_in_len` additional bytes of plaintext are
// encrypted and authenticated, and the ciphertext is written (before the tag)
// to |out_tag|. |max_out_tag_len| must be sized to allow for the additional
// |extra_in_len| bytes.
// to `out_tag`. `max_out_tag_len` must be sized to allow for the additional
// `extra_in_len` bytes.
//
// The length of |nonce|, |nonce_len|, must be equal to the result of
// |EVP_AEAD_nonce_length| for this AEAD.
// The length of `nonce`, `nonce_len`, must be equal to the result of
// `EVP_AEAD_nonce_length` for this AEAD.
//
// |EVP_AEAD_CTX_seal_scatter| never results in a partial output. If
// |max_out_tag_len| is insufficient, zero will be returned. If any error
// occurs, |out| and |out_tag| will be filled with zero bytes and |*out_tag_len|
// `EVP_AEAD_CTX_seal_scatter` never results in a partial output. If
// `max_out_tag_len` is insufficient, zero will be returned. If any error
// occurs, `out` and `out_tag` will be filled with zero bytes and `*out_tag_len`
// set to zero.
//
// If |in| and |out| alias then |out| must be == |in|. |out_tag| may not alias
// If `in` and `out` alias then `out` must be == `in`. `out_tag` may not alias
// any other argument.
OPENSSL_EXPORT int EVP_AEAD_CTX_seal_scatter(
const EVP_AEAD_CTX *ctx, uint8_t *out, uint8_t *out_tag,
@@ -377,81 +377,81 @@ OPENSSL_EXPORT int EVP_AEAD_CTX_seal_scatter(
size_t nonce_len, const uint8_t *in, size_t in_len, const uint8_t *extra_in,
size_t extra_in_len, const uint8_t *ad, size_t ad_len);
// EVP_AEAD_CTX_open_gather decrypts and authenticates |in_len| bytes from |in|
// and authenticates |ad_len| bytes from |ad| using |in_tag_len| bytes of
// authentication tag from |in_tag|. If successful, it writes |in_len| bytes of
// plaintext to |out|. It returns one on success and zero otherwise.
// EVP_AEAD_CTX_open_gather decrypts and authenticates `in_len` bytes from `in`
// and authenticates `ad_len` bytes from `ad` using `in_tag_len` bytes of
// authentication tag from `in_tag`. If successful, it writes `in_len` bytes of
// plaintext to `out`. It returns one on success and zero otherwise.
//
// This function may be called concurrently with itself or any other seal/open
// function on the same |EVP_AEAD_CTX|.
// function on the same `EVP_AEAD_CTX`.
//
// The length of |nonce|, |nonce_len|, must be equal to the result of
// |EVP_AEAD_nonce_length| for this AEAD.
// The length of `nonce`, `nonce_len`, must be equal to the result of
// `EVP_AEAD_nonce_length` for this AEAD.
//
// |EVP_AEAD_CTX_open_gather| never results in a partial output. If any error
// occurs, |out| will be filled with zero bytes.
// `EVP_AEAD_CTX_open_gather` never results in a partial output. If any error
// occurs, `out` will be filled with zero bytes.
//
// If |in| and |out| alias then |out| must be == |in|.
// If `in` and `out` alias then `out` must be == `in`.
OPENSSL_EXPORT int EVP_AEAD_CTX_open_gather(
const EVP_AEAD_CTX *ctx, uint8_t *out, const uint8_t *nonce,
size_t nonce_len, const uint8_t *in, size_t in_len, const uint8_t *in_tag,
size_t in_tag_len, const uint8_t *ad, size_t ad_len);
// crypto_ivec_st (aka |CRYPTO_IVEC|) combines a pointer to input data with its
// crypto_ivec_st (aka `CRYPTO_IVEC`) combines a pointer to input data with its
// length. It is usually passed as an array of length of at most
// |CRYPTO_IOVEC_MAX|.
// `CRYPTO_IOVEC_MAX`.
struct crypto_ivec_st {
const uint8_t *in;
size_t len;
};
// crypto_iovec_st (aka |CRYPTO_IOVEC| combines a pointer to input data and a
// crypto_iovec_st (aka `CRYPTO_IOVEC` combines a pointer to input data and a
// pointer to an output buffer with their common length. It is usually passed
// as an array of length of at most |CRYPTO_IOVEC_MAX|.
// as an array of length of at most `CRYPTO_IOVEC_MAX`.
struct crypto_iovec_st {
// |out| and |in| must be disjoint or equal
// `out` and `in` must be disjoint or equal
uint8_t *out;
const uint8_t *in;
size_t len;
};
// CRYPTO_IOVEC_MAX is the maximum number of entries in an |CRYPTO_IOVEC| or
// |CRYPTO_IVEC| parameter.
// CRYPTO_IOVEC_MAX is the maximum number of entries in an `CRYPTO_IOVEC` or
// `CRYPTO_IVEC` parameter.
#define CRYPTO_IOVEC_MAX 16
// EVP_AEAD_CTX_sealv encrypts and authenticates the |in| bytes from |iovec|
// and authenticates the |aadvec| bytes. It writes the same amount of
// ciphertext to the |out| pointers of |iovec| and the authentication tag to
// |out_tag|. It returns one on success and zero otherwise.
// EVP_AEAD_CTX_sealv encrypts and authenticates the `in` bytes from `iovec`
// and authenticates the `aadvec` bytes. It writes the same amount of
// ciphertext to the `out` pointers of `iovec` and the authentication tag to
// `out_tag`. It returns one on success and zero otherwise.
//
// This function computes the same output as |EVP_AEAD_CTX_seal_scatter|, but
// This function computes the same output as `EVP_AEAD_CTX_seal_scatter`, but
// without requiring the input or output to be a contiguous buffer. The
// individual input and output pieces are logically concatenated for a single
// operation; their boundaries are not semantically significant and will not
// impact the output.
//
// This function may be called concurrently with itself or any other seal/open
// function on the same |EVP_AEAD_CTX|.
// function on the same `EVP_AEAD_CTX`.
//
// Exactly |len| bytes are written to each |out| member of the |iovec|, and up
// to |EVP_AEAD_max_overhead+extra_in_len| bytes to |out_tag|. On successful
// return, |*out_tag_len| is set to the actual number of bytes written to
// |out_tag|.
// Exactly `len` bytes are written to each `out` member of the `iovec`, and up
// to `EVP_AEAD_max_overhead+extra_in_len` bytes to `out_tag`. On successful
// return, `*out_tag_len` is set to the actual number of bytes written to
// `out_tag`.
//
// The length of |nonce|, |nonce_len|, must be equal to the result of
// |EVP_AEAD_nonce_length| for this AEAD.
// The length of `nonce`, `nonce_len`, must be equal to the result of
// `EVP_AEAD_nonce_length` for this AEAD.
//
// |EVP_AEAD_CTX_sealv| never results in a partial output. If |max_out_tag_len|
// is insufficient, zero will be returned. If any error occurs, the |out|
// members of the |iovec| and |out_tag| will be filled with zero bytes and
// |*out_tag_len| set to zero.
// `EVP_AEAD_CTX_sealv` never results in a partial output. If `max_out_tag_len`
// is insufficient, zero will be returned. If any error occurs, the `out`
// members of the `iovec` and `out_tag` will be filled with zero bytes and
// `*out_tag_len` set to zero.
//
// No output pointer may alias any other pointer passed to this function either
// directly or via |iovec| and |aadvec|, with the one exception that it is
// permitted for the same |iovec| member's |in| and |out| members to be equal
// directly or via `iovec` and `aadvec`, with the one exception that it is
// permitted for the same `iovec` member's `in` and `out` members to be equal
// (in-place operation).
//
// |num_iovec| and |num_aadvec| must be <= |CRYPTO_IOVEC_MAX|.
// `num_iovec` and `num_aadvec` must be <= `CRYPTO_IOVEC_MAX`.
OPENSSL_EXPORT
int EVP_AEAD_CTX_sealv(const EVP_AEAD_CTX *ctx, const CRYPTO_IOVEC *iovec,
size_t num_iovec, uint8_t *out_tag, size_t *out_tag_len,
@@ -459,80 +459,80 @@ int EVP_AEAD_CTX_sealv(const EVP_AEAD_CTX *ctx, const CRYPTO_IOVEC *iovec,
size_t nonce_len, const CRYPTO_IVEC *aadvec,
size_t num_aadvec);
// EVP_AEAD_CTX_openv authenticates the |in| bytes from |iovec| and |aadvec|,
// and decrypts the |in| bytes to the |out| pointers of |iovec|. It returns one
// EVP_AEAD_CTX_openv authenticates the `in` bytes from `iovec` and `aadvec`,
// and decrypts the `in` bytes to the `out` pointers of `iovec`. It returns one
// on success and zero otherwise.
//
// This function computes the same output as |EVP_AEAD_CTX_open|, but without
// This function computes the same output as `EVP_AEAD_CTX_open`, but without
// requiring the input or output to be a contiguous buffer. The individual
// input and output pieces are logically concatenated for a single operation;
// their boundaries are not semantically significant and will not impact the
// output.
//
// This function may (and usually will) output less than the total length of
// |iovec|. In this case, it outputs to a prefix of |iovec|'s output space,
// `iovec`. In this case, it outputs to a prefix of `iovec`'s output space,
// then returns the length of what was actually written.
//
// In AEADs with a fixed-length authentication tag, the tag is treated as if it
// were appended to the ciphertext, and successful outputs will always be
// exactly the tag length shorter. To open with a separate, detached tag,
// either provide it as a separate |CRYPTO_IOVEC|, or use
// |EVP_AEAD_CTX_openv_detached|. The latter may be more convenient, one does
// not need consider the possibility of output to the final |CRYPTO_IOVEC|.
// either provide it as a separate `CRYPTO_IOVEC`, or use
// `EVP_AEAD_CTX_openv_detached`. The latter may be more convenient, one does
// not need consider the possibility of output to the final `CRYPTO_IOVEC`.
//
// This function may be called concurrently with itself or any other seal/open
// function on the same |EVP_AEAD_CTX|.
// function on the same `EVP_AEAD_CTX`.
//
// The length of |nonce|, |nonce_len|, must be equal to the result of
// |EVP_AEAD_nonce_length| for this AEAD.
// The length of `nonce`, `nonce_len`, must be equal to the result of
// `EVP_AEAD_nonce_length` for this AEAD.
//
// |EVP_AEAD_CTX_openv| never results in a partial output. If any error occurs,
// |out| will be filled with zero bytes and |*out_len| set to zero.
// `EVP_AEAD_CTX_openv` never results in a partial output. If any error occurs,
// `out` will be filled with zero bytes and `*out_len` set to zero.
//
// No output pointer may alias any other pointer passed to this function either
// directly or via |iovec| and |aadvec|, with the one exception that it is
// permitted for the same |iovec| member's |in| and |out| members to be equal
// directly or via `iovec` and `aadvec`, with the one exception that it is
// permitted for the same `iovec` member's `in` and `out` members to be equal
// (in-place operation).
//
// |num_iovec| and |num_aadvec| must be <= |CRYPTO_IOVEC_MAX|.
// `num_iovec` and `num_aadvec` must be <= `CRYPTO_IOVEC_MAX`.
OPENSSL_EXPORT
int EVP_AEAD_CTX_openv(const EVP_AEAD_CTX *ctx, const CRYPTO_IOVEC *iovec,
size_t num_iovec, size_t *out_total_bytes,
const uint8_t *nonce, size_t nonce_len,
const CRYPTO_IVEC *aadvec, size_t num_aadvec);
// EVP_AEAD_CTX_openv_detached authenticates the |in| bytes from |iovec| and
// |aadvec| using |in_tag_len| bytes of authentication tag from |in_tag|. If
// successful, it writes the plaintext of the |in| bytes to the |out| pointers
// of |iovec|. It returns one on success and zero otherwise.
// EVP_AEAD_CTX_openv_detached authenticates the `in` bytes from `iovec` and
// `aadvec` using `in_tag_len` bytes of authentication tag from `in_tag`. If
// successful, it writes the plaintext of the `in` bytes to the `out` pointers
// of `iovec`. It returns one on success and zero otherwise.
//
// This function is usable with AEADs whose output can be split into a
// ciphertext portion, with the same length as the plaintext, and a
// fixed-length authentication tag. If the AEAD has a variable-length overhead,
// this function will return zero. Such AEADs can only be used with
// |EVP_AEAD_CTX_openv|.
// `EVP_AEAD_CTX_openv`.
//
// This function computes the same output as |EVP_AEAD_CTX_open|, but with a
// This function computes the same output as `EVP_AEAD_CTX_open`, but with a
// detached tag and without requiring the input or output to be a contiguous
// buffer. The individual input and output pieces are logically concatenated
// for a single operation; their boundaries are not semantically significant
// and will not impact the output.
//
// This function may be called concurrently with itself or any other seal/open
// function on the same |EVP_AEAD_CTX|.
// function on the same `EVP_AEAD_CTX`.
//
// The length of |nonce|, |nonce_len|, must be equal to the result of
// |EVP_AEAD_nonce_length| for this AEAD.
// The length of `nonce`, `nonce_len`, must be equal to the result of
// `EVP_AEAD_nonce_length` for this AEAD.
//
// |EVP_AEAD_CTX_openv_detached| never results in a partial output. If any
// error occurs, |out| will be filled with zero bytes.
// `EVP_AEAD_CTX_openv_detached` never results in a partial output. If any
// error occurs, `out` will be filled with zero bytes.
//
// No output pointer may alias any other pointer passed to this function either
// directly or via |iovec| and |aadvec|, with the one exception that it is
// permitted for the same |iovec| member's |in| and |out| members to be equal
// directly or via `iovec` and `aadvec`, with the one exception that it is
// permitted for the same `iovec` member's `in` and `out` members to be equal
// (in-place operation).
//
// |num_iovec| and |num_aadvec| must be <= |CRYPTO_IOVEC_MAX|.
// `num_iovec` and `num_aadvec` must be <= `CRYPTO_IOVEC_MAX`.
OPENSSL_EXPORT
int EVP_AEAD_CTX_openv_detached(const EVP_AEAD_CTX *ctx,
const CRYPTO_IOVEC *iovec, size_t num_iovec,
@@ -540,7 +540,7 @@ int EVP_AEAD_CTX_openv_detached(const EVP_AEAD_CTX *ctx,
const uint8_t *in_tag, size_t in_tag_len,
const CRYPTO_IVEC *aadvec, size_t num_aadvec);
// EVP_AEAD_CTX_aead returns the underlying AEAD for |ctx|, or NULL if one has
// EVP_AEAD_CTX_aead returns the underlying AEAD for `ctx`, or NULL if one has
// not been set.
OPENSSL_EXPORT const EVP_AEAD *EVP_AEAD_CTX_aead(const EVP_AEAD_CTX *ctx);
@@ -549,9 +549,9 @@ OPENSSL_EXPORT const EVP_AEAD *EVP_AEAD_CTX_aead(const EVP_AEAD_CTX *ctx);
//
// These AEAD primitives do not meet the definition of generic AEADs. They are
// all specific to TLS and should not be used outside of that context. They must
// be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, and may
// be initialized with `EVP_AEAD_CTX_init_with_direction`, are stateful, and may
// not be used concurrently. Any nonces are used as IVs, so they must be
// unpredictable. They only accept an |ad| parameter of length 11 (the standard
// unpredictable. They only accept an `ad` parameter of length 11 (the standard
// TLS one with length omitted).
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls(void);
@@ -590,15 +590,15 @@ enum evp_aead_direction_t {
evp_aead_seal,
};
// EVP_AEAD_CTX_init_with_direction calls |EVP_AEAD_CTX_init| for normal
// AEADs. For TLS-specific and SSL3-specific AEADs, it initializes |ctx| for a
// EVP_AEAD_CTX_init_with_direction calls `EVP_AEAD_CTX_init` for normal
// AEADs. For TLS-specific and SSL3-specific AEADs, it initializes `ctx` for a
// given direction.
OPENSSL_EXPORT int EVP_AEAD_CTX_init_with_direction(
EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, const uint8_t *key, size_t key_len,
size_t tag_len, enum evp_aead_direction_t dir);
// EVP_AEAD_CTX_get_iv sets |*out_len| to the length of the IV for |ctx| and
// sets |*out_iv| to point to that many bytes of the current IV. This is only
// EVP_AEAD_CTX_get_iv sets `*out_len` to the length of the IV for `ctx` and
// sets `*out_iv` to point to that many bytes of the current IV. This is only
// meaningful for AEADs with implicit IVs (i.e. CBC mode in TLS 1.0).
//
// It returns one on success or zero on error.
@@ -606,17 +606,17 @@ OPENSSL_EXPORT int EVP_AEAD_CTX_get_iv(const EVP_AEAD_CTX *ctx,
const uint8_t **out_iv, size_t *out_len);
// EVP_AEAD_CTX_tag_len computes the exact byte length of the tag written by
// |EVP_AEAD_CTX_seal_scatter| and writes it to |*out_tag_len|. It returns one
// on success or zero on error. |in_len| and |extra_in_len| must equal the
// arguments of the same names passed to |EVP_AEAD_CTX_seal_scatter|.
// `EVP_AEAD_CTX_seal_scatter` and writes it to `*out_tag_len`. It returns one
// on success or zero on error. `in_len` and `extra_in_len` must equal the
// arguments of the same names passed to `EVP_AEAD_CTX_seal_scatter`.
//
// To compute the exact byte length of the output written by
// |EVP_AEAD_CTX_seal|, set |extra_in_len| to zero and add |in_len| to the
// `EVP_AEAD_CTX_seal`, set `extra_in_len` to zero and add `in_len` to the
// result.
//
// To compute the exact byte length of the tag written by |EVP_AEAD_CTX_sealv|,
// set |in_len| to the sum of |len| over the entire |iovec|, and set
// |extra_in_len| to zero.
// To compute the exact byte length of the tag written by `EVP_AEAD_CTX_sealv`,
// set `in_len` to the sum of `len` over the entire `iovec`, and set
// `extra_in_len` to zero.
OPENSSL_EXPORT int EVP_AEAD_CTX_tag_len(const EVP_AEAD_CTX *ctx,
size_t *out_tag_len,
const size_t in_len,
include/openssl/aes.h
+43 -43
View File
@@ -41,39 +41,39 @@ struct aes_key_st {
};
typedef struct aes_key_st AES_KEY;
// AES_set_encrypt_key configures |aeskey| to encrypt with the |bits|-bit key,
// |key|. |key| must point to |bits|/8 bytes. It returns zero on success and a
// negative number if |bits| is an invalid AES key size.
// AES_set_encrypt_key configures `aeskey` to encrypt with the `bits`-bit key,
// `key`. `key` must point to `bits`/8 bytes. It returns zero on success and a
// negative number if `bits` is an invalid AES key size.
//
// WARNING: this function breaks the usual return value convention.
OPENSSL_EXPORT int AES_set_encrypt_key(const uint8_t *key, unsigned bits,
AES_KEY *aeskey);
// AES_set_decrypt_key configures |aeskey| to decrypt with the |bits|-bit key,
// |key|. |key| must point to |bits|/8 bytes. It returns zero on success and a
// negative number if |bits| is an invalid AES key size.
// AES_set_decrypt_key configures `aeskey` to decrypt with the `bits`-bit key,
// `key`. `key` must point to `bits`/8 bytes. It returns zero on success and a
// negative number if `bits` is an invalid AES key size.
//
// WARNING: this function breaks the usual return value convention.
OPENSSL_EXPORT int AES_set_decrypt_key(const uint8_t *key, unsigned bits,
AES_KEY *aeskey);
// AES_encrypt encrypts a single block from |in| to |out| with |key|. The |in|
// and |out| pointers may overlap.
// AES_encrypt encrypts a single block from `in` to `out` with `key`. The `in`
// and `out` pointers may overlap.
OPENSSL_EXPORT void AES_encrypt(const uint8_t *in, uint8_t *out,
const AES_KEY *key);
// AES_decrypt decrypts a single block from |in| to |out| with |key|. The |in|
// and |out| pointers may overlap.
// AES_decrypt decrypts a single block from `in` to `out` with `key`. The `in`
// and `out` pointers may overlap.
OPENSSL_EXPORT void AES_decrypt(const uint8_t *in, uint8_t *out,
const AES_KEY *key);
// Block cipher modes.
// AES_ctr128_encrypt encrypts (or decrypts, it's the same in CTR mode) |len|
// bytes from |in| to |out|. The |num| parameter must be set to zero on the
// first call and |ivec| will be incremented. This function may be called
// in-place with |in| equal to |out|, but otherwise the buffers may not
// AES_ctr128_encrypt encrypts (or decrypts, it's the same in CTR mode) `len`
// bytes from `in` to `out`. The `num` parameter must be set to zero on the
// first call and `ivec` will be incremented. This function may be called
// in-place with `in` equal to `out`, but otherwise the buffers may not
// partially overlap. A partial overlap may overwrite input data before it is
// read.
OPENSSL_EXPORT void AES_ctr128_encrypt(const uint8_t *in, uint8_t *out,
@@ -82,34 +82,34 @@ OPENSSL_EXPORT void AES_ctr128_encrypt(const uint8_t *in, uint8_t *out,
uint8_t ecount_buf[AES_BLOCK_SIZE],
unsigned int *num);
// AES_ecb_encrypt encrypts (or decrypts, if |enc| == |AES_DECRYPT|) a single,
// 16 byte block from |in| to |out|. This function may be called in-place with
// |in| equal to |out|, but otherwise the buffers may not partially overlap. A
// AES_ecb_encrypt encrypts (or decrypts, if `enc` == `AES_DECRYPT`) a single,
// 16 byte block from `in` to `out`. This function may be called in-place with
// `in` equal to `out`, but otherwise the buffers may not partially overlap. A
// partial overlap may overwrite input data before it is read.
OPENSSL_EXPORT void AES_ecb_encrypt(const uint8_t *in, uint8_t *out,
const AES_KEY *key, const int enc);
// AES_cbc_encrypt encrypts (or decrypts, if |enc| == |AES_DECRYPT|) |len|
// bytes from |in| to |out|. The length must be a multiple of the block size.
// This function may be called in-place with |in| equal to |out|, but otherwise
// AES_cbc_encrypt encrypts (or decrypts, if `enc` == `AES_DECRYPT`) `len`
// bytes from `in` to `out`. The length must be a multiple of the block size.
// This function may be called in-place with `in` equal to `out`, but otherwise
// the buffers may not partially overlap. A partial overlap may overwrite input
// data before it is read.
OPENSSL_EXPORT void AES_cbc_encrypt(const uint8_t *in, uint8_t *out, size_t len,
const AES_KEY *key, uint8_t *ivec,
const int enc);
// AES_ofb128_encrypt encrypts (or decrypts, it's the same in OFB mode) |len|
// bytes from |in| to |out|. The |num| parameter must be set to zero on the
// first call. This function may be called in-place with |in| equal to |out|,
// AES_ofb128_encrypt encrypts (or decrypts, it's the same in OFB mode) `len`
// bytes from `in` to `out`. The `num` parameter must be set to zero on the
// first call. This function may be called in-place with `in` equal to `out`,
// but otherwise the buffers may not partially overlap. A partial overlap may
// overwrite input data before it is read.
OPENSSL_EXPORT void AES_ofb128_encrypt(const uint8_t *in, uint8_t *out,
size_t len, const AES_KEY *key,
uint8_t *ivec, int *num);
// AES_cfb128_encrypt encrypts (or decrypts, if |enc| == |AES_DECRYPT|) |len|
// bytes from |in| to |out|. The |num| parameter must be set to zero on the
// first call. This function may be called in-place with |in| equal to |out|,
// AES_cfb128_encrypt encrypts (or decrypts, if `enc` == `AES_DECRYPT`) `len`
// bytes from `in` to `out`. The `num` parameter must be set to zero on the
// first call. This function may be called in-place with `in` equal to `out`,
// but otherwise the buffers may not partially overlap. A partial overlap may
// overwrite input data before it is read.
OPENSSL_EXPORT void AES_cfb128_encrypt(const uint8_t *in, uint8_t *out,
@@ -123,18 +123,18 @@ OPENSSL_EXPORT void AES_cfb128_encrypt(const uint8_t *in, uint8_t *out,
// should never be used except to interoperate with existing systems that use
// this mode.
// AES_wrap_key performs AES key wrap on |in| which must be a multiple of 8
// bytes. |iv| must point to an 8 byte value or be NULL to use the default IV.
// |key| must have been configured for encryption. On success, it writes
// |in_len| + 8 bytes to |out| and returns |in_len| + 8. Otherwise, it returns
// AES_wrap_key performs AES key wrap on `in` which must be a multiple of 8
// bytes. `iv` must point to an 8 byte value or be NULL to use the default IV.
// `key` must have been configured for encryption. On success, it writes
// `in_len` + 8 bytes to `out` and returns `in_len` + 8. Otherwise, it returns
// -1.
OPENSSL_EXPORT int AES_wrap_key(const AES_KEY *key, const uint8_t *iv,
uint8_t *out, const uint8_t *in, size_t in_len);
// AES_unwrap_key performs AES key unwrap on |in| which must be a multiple of 8
// bytes. |iv| must point to an 8 byte value or be NULL to use the default IV.
// |key| must have been configured for decryption. On success, it writes
// |in_len| - 8 bytes to |out| and returns |in_len| - 8. Otherwise, it returns
// AES_unwrap_key performs AES key unwrap on `in` which must be a multiple of 8
// bytes. `iv` must point to an 8 byte value or be NULL to use the default IV.
// `key` must have been configured for decryption. On success, it writes
// `in_len` - 8 bytes to `out` and returns `in_len` - 8. Otherwise, it returns
// -1.
OPENSSL_EXPORT int AES_unwrap_key(const AES_KEY *key, const uint8_t *iv,
uint8_t *out, const uint8_t *in,
@@ -147,20 +147,20 @@ OPENSSL_EXPORT int AES_unwrap_key(const AES_KEY *key, const uint8_t *iv,
// 5649. They should never be used except to interoperate with existing systems
// that use this mode.
// AES_wrap_key_padded performs a padded AES key wrap on |in| which must be
// between 1 and 2^32-1 bytes. |key| must have been configured for encryption.
// On success it writes at most |max_out| bytes of ciphertext to |out|, sets
// |*out_len| to the number of bytes written, and returns one. On failure it
// returns zero. To ensure success, set |max_out| to at least |in_len| + 15.
// AES_wrap_key_padded performs a padded AES key wrap on `in` which must be
// between 1 and 2^32-1 bytes. `key` must have been configured for encryption.
// On success it writes at most `max_out` bytes of ciphertext to `out`, sets
// `*out_len` to the number of bytes written, and returns one. On failure it
// returns zero. To ensure success, set `max_out` to at least `in_len` + 15.
OPENSSL_EXPORT int AES_wrap_key_padded(const AES_KEY *key, uint8_t *out,
size_t *out_len, size_t max_out,
const uint8_t *in, size_t in_len);
// AES_unwrap_key_padded performs a padded AES key unwrap on |in| which must be
// a multiple of 8 bytes. |key| must have been configured for decryption. On
// success it writes at most |max_out| bytes to |out|, sets |*out_len| to the
// AES_unwrap_key_padded performs a padded AES key unwrap on `in` which must be
// a multiple of 8 bytes. `key` must have been configured for decryption. On
// success it writes at most `max_out` bytes to `out`, sets `*out_len` to the
// number of bytes written, and returns one. On failure it returns zero. Setting
// |max_out| to |in_len| is a sensible estimate.
// `max_out` to `in_len` is a sensible estimate.
OPENSSL_EXPORT int AES_unwrap_key_padded(const AES_KEY *key, uint8_t *out,
size_t *out_len, size_t max_out,
const uint8_t *in, size_t in_len);
include/openssl/asm_base.h
+12 -12
View File
@@ -25,7 +25,7 @@
// Every assembly file must include this header. Some linker features require
// all object files to be tagged with some section metadata. This header file,
// when included in assembly, adds that metadata. It also makes defines like
// |OPENSSL_X86_64| available and includes the prefixing macros.
// `OPENSSL_X86_64` available and includes the prefixing macros.
//
// Including this header in an assembly file imples:
//
@@ -70,7 +70,7 @@
#if defined(OPENSSL_ARM) || defined(OPENSSL_AARCH64)
// We require the ARM assembler provide |__ARM_ARCH| from Arm C Language
// We require the ARM assembler provide `__ARM_ARCH` from Arm C Language
// Extensions (ACLE). This is supported in GCC 4.8+ and Clang 3.2+. MSVC does
// not implement ACLE, but we require Clang's assembler on Windows.
#if !defined(__ARM_ARCH)
@@ -92,12 +92,12 @@
// features which require emitting a .note.gnu.property section with the
// appropriate architecture-dependent feature bits set.
//
// |AARCH64_SIGN_LINK_REGISTER| and |AARCH64_VALIDATE_LINK_REGISTER| expand to
// PACIxSP and AUTIxSP, respectively. |AARCH64_SIGN_LINK_REGISTER| should be
// `AARCH64_SIGN_LINK_REGISTER` and `AARCH64_VALIDATE_LINK_REGISTER` expand to
// PACIxSP and AUTIxSP, respectively. `AARCH64_SIGN_LINK_REGISTER` should be
// used immediately before saving the LR register (x30) to the stack.
// |AARCH64_VALIDATE_LINK_REGISTER| should be used immediately after restoring
// it. Note |AARCH64_SIGN_LINK_REGISTER|'s modifications to LR must be undone
// with |AARCH64_VALIDATE_LINK_REGISTER| before RET. The SP register must also
// `AARCH64_VALIDATE_LINK_REGISTER` should be used immediately after restoring
// it. Note `AARCH64_SIGN_LINK_REGISTER`'s modifications to LR must be undone
// with `AARCH64_VALIDATE_LINK_REGISTER` before RET. The SP register must also
// have the same value at the two points. For example:
//
// .global f
@@ -110,11 +110,11 @@
// AARCH64_VALIDATE_LINK_REGISTER
// ret
//
// |AARCH64_VALID_CALL_TARGET| expands to BTI 'c'. Either it, or
// |AARCH64_SIGN_LINK_REGISTER|, must be used at every point that may be an
// `AARCH64_VALID_CALL_TARGET` expands to BTI 'c'. Either it, or
// `AARCH64_SIGN_LINK_REGISTER`, must be used at every point that may be an
// indirect call target. In particular, all symbols exported from a file must
// begin with one of these macros. For example, a leaf function that does not
// save LR can instead use |AARCH64_VALID_CALL_TARGET|:
// save LR can instead use `AARCH64_VALID_CALL_TARGET`:
//
// .globl return_zero
// return_zero:
@@ -123,7 +123,7 @@
// ret
//
// A non-leaf function which does not immediately save LR may need both macros
// because |AARCH64_SIGN_LINK_REGISTER| appears late. For example, the function
// because `AARCH64_SIGN_LINK_REGISTER` appears late. For example, the function
// may jump to an alternate implementation before setting up the stack:
//
// .globl with_early_jump
@@ -145,7 +145,7 @@
//
// These annotations are only required with indirect calls. Private symbols that
// are only the target of direct calls do not require annotations. Also note
// that |AARCH64_VALID_CALL_TARGET| is only valid for indirect calls (BLR), not
// that `AARCH64_VALID_CALL_TARGET` is only valid for indirect calls (BLR), not
// indirect jumps (BR). Indirect jumps in assembly are currently not supported
// and would require a macro for BTI 'j'.
//
include/openssl/asn1.h
+597 -597
View File
File diff suppressed because it is too large Load Diff
include/openssl/asn1t.h
+2 -2
View File
@@ -26,8 +26,8 @@ extern "C" {
/* Legacy ASN.1 library template definitions.
*
* This header is used to define new types in OpenSSL's ASN.1 implementation. It
* is deprecated and will be unexported from the library. Use the new |CBS| and
* |CBB| library in <openssl/bytestring.h> instead. */
* is deprecated and will be unexported from the library. Use the new `CBS` and
* `CBB` library in <openssl/bytestring.h> instead. */
typedef struct ASN1_TEMPLATE_st ASN1_TEMPLATE;
include/openssl/base.h
+8 -8
View File
@@ -51,7 +51,7 @@ extern "C" {
#if defined(__APPLE__)
// Note |TARGET_OS_MAC| is set for all Apple OS variants. |TARGET_OS_OSX|
// Note `TARGET_OS_MAC` is set for all Apple OS variants. `TARGET_OS_OSX`
// targets macOS specifically.
#if defined(TARGET_OS_OSX) && TARGET_OS_OSX
#define OPENSSL_MACOS
@@ -182,7 +182,7 @@ extern "C" {
#if defined(BORINGSSL_ALWAYS_USE_STATIC_INLINE)
// Add OPENSSL_UNUSED so that, should an inline function be emitted via macro
// (e.g. a |STACK_OF(T)| implementation) in a source file without tripping
// (e.g. a `STACK_OF(T)` implementation) in a source file without tripping
// clang's -Wunused-function.
#define OPENSSL_INLINE static inline OPENSSL_UNUSED
#else
@@ -208,23 +208,23 @@ enum ssl_verify_result_t BORINGSSL_ENUM_INT;
#endif
// ossl_ssize_t is a signed type which is large enough to fit the size of any
// valid memory allocation. We prefer using |size_t|, but sometimes we need a
// valid memory allocation. We prefer using `size_t`, but sometimes we need a
// signed type for OpenSSL API compatibility. This type can be used in such
// cases to avoid overflow.
//
// Not all |size_t| values fit in |ossl_ssize_t|, but all |size_t| values that
// Not all `size_t` values fit in `ossl_ssize_t`, but all `size_t` values that
// are sizes of or indices into C objects, can be converted without overflow.
typedef ptrdiff_t ossl_ssize_t;
// CBS_ASN1_TAG is the type used by |CBS| and |CBB| for ASN.1 tags. See that
// CBS_ASN1_TAG is the type used by `CBS` and `CBB` for ASN.1 tags. See that
// header for details. This type is defined in base.h as a forward declaration.
typedef uint32_t CBS_ASN1_TAG;
// CRYPTO_THREADID is a dummy value.
typedef int CRYPTO_THREADID;
// An |ASN1_NULL| is an opaque type. asn1.h represents the ASN.1 NULL value as
// an opaque, non-NULL |ASN1_NULL*| pointer.
// An `ASN1_NULL` is an opaque type. asn1.h represents the ASN.1 NULL value as
// an opaque, non-NULL `ASN1_NULL*` pointer.
typedef struct asn1_null_st ASN1_NULL;
// CRYPTO_MUST_BE_NULL is an opaque type that is never returned from BoringSSL.
@@ -365,7 +365,7 @@ typedef struct x509_store_st X509_STORE;
typedef void *OPENSSL_BLOCK;
// BSSL_CHECK aborts if |condition| is not true.
// BSSL_CHECK aborts if `condition` is not true.
#define BSSL_CHECK(condition) \
do { \
if (!(condition)) { \
include/openssl/base64.h
+30 -30
View File
@@ -33,29 +33,29 @@ extern "C" {
// Encoding
// EVP_EncodeBlock encodes |src_len| bytes from |src| and writes the
// result to |dst| with a trailing NUL. It returns the number of bytes
// EVP_EncodeBlock encodes `src_len` bytes from `src` and writes the
// result to `dst` with a trailing NUL. It returns the number of bytes
// written, not including this trailing NUL.
OPENSSL_EXPORT size_t EVP_EncodeBlock(uint8_t *dst, const uint8_t *src,
size_t src_len);
// EVP_EncodedLength sets |*out_len| to the number of bytes that will be needed
// to call |EVP_EncodeBlock| on an input of length |len|. This includes the
// final NUL that |EVP_EncodeBlock| writes. It returns one on success or zero
// EVP_EncodedLength sets `*out_len` to the number of bytes that will be needed
// to call `EVP_EncodeBlock` on an input of length `len`. This includes the
// final NUL that `EVP_EncodeBlock` writes. It returns one on success or zero
// on error.
OPENSSL_EXPORT int EVP_EncodedLength(size_t *out_len, size_t len);
// Decoding
// EVP_DecodedLength sets |*out_len| to the maximum number of bytes that will
// be needed to call |EVP_DecodeBase64| on an input of length |len|. It returns
// one on success or zero if |len| is not a valid length for a base64-encoded
// EVP_DecodedLength sets `*out_len` to the maximum number of bytes that will
// be needed to call `EVP_DecodeBase64` on an input of length `len`. It returns
// one on success or zero if `len` is not a valid length for a base64-encoded
// string.
OPENSSL_EXPORT int EVP_DecodedLength(size_t *out_len, size_t len);
// EVP_DecodeBase64 decodes |in_len| bytes from base64 and writes
// |*out_len| bytes to |out|. |max_out| is the size of the output
// EVP_DecodeBase64 decodes `in_len` bytes from base64 and writes
// `*out_len` bytes to `out`. `max_out` is the size of the output
// buffer. If it is not enough for the maximum output size, the
// operation fails. It returns one on success or zero on error.
OPENSSL_EXPORT int EVP_DecodeBase64(uint8_t *out, size_t *out_len,
@@ -69,15 +69,15 @@ OPENSSL_EXPORT int EVP_DecodeBase64(uint8_t *out, size_t *out_len,
// very specific to PEM. It is also very lenient of invalid input. Use of any of
// these functions is thus deprecated.
// EVP_ENCODE_CTX_new returns a newly-allocated |EVP_ENCODE_CTX| or NULL on
// error. The caller must release the result with |EVP_ENCODE_CTX_free| when
// EVP_ENCODE_CTX_new returns a newly-allocated `EVP_ENCODE_CTX` or NULL on
// error. The caller must release the result with `EVP_ENCODE_CTX_free` when
// done.
OPENSSL_EXPORT EVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void);
// EVP_ENCODE_CTX_free releases memory associated with |ctx|.
// EVP_ENCODE_CTX_free releases memory associated with `ctx`.
OPENSSL_EXPORT void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx);
// EVP_EncodeInit initialises |*ctx|, which is typically stack
// EVP_EncodeInit initialises `*ctx`, which is typically stack
// allocated, for an encoding operation.
//
// NOTE: The encoding operation breaks its output with newlines every
@@ -85,29 +85,29 @@ OPENSSL_EXPORT void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx);
// EVP_EncodeBlock to encode raw base64.
OPENSSL_EXPORT void EVP_EncodeInit(EVP_ENCODE_CTX *ctx);
// EVP_EncodeUpdate encodes |in_len| bytes from |in| and writes an encoded
// version of them to |out| and sets |*out_len| to the number of bytes written.
// Some state may be contained in |ctx| so |EVP_EncodeFinal| must be used to
// EVP_EncodeUpdate encodes `in_len` bytes from `in` and writes an encoded
// version of them to `out` and sets `*out_len` to the number of bytes written.
// Some state may be contained in `ctx` so `EVP_EncodeFinal` must be used to
// flush it before using the encoded data.
OPENSSL_EXPORT void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, uint8_t *out,
int *out_len, const uint8_t *in,
size_t in_len);
// EVP_EncodeFinal flushes any remaining output bytes from |ctx| to |out| and
// sets |*out_len| to the number of bytes written.
// EVP_EncodeFinal flushes any remaining output bytes from `ctx` to `out` and
// sets `*out_len` to the number of bytes written.
OPENSSL_EXPORT void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, uint8_t *out,
int *out_len);
// EVP_DecodeInit initialises |*ctx|, which is typically stack allocated, for
// EVP_DecodeInit initialises `*ctx`, which is typically stack allocated, for
// a decoding operation.
//
// TODO(davidben): This isn't a straight-up base64 decode either. Document
// and/or fix exactly what's going on here; maximum line length and such.
OPENSSL_EXPORT void EVP_DecodeInit(EVP_ENCODE_CTX *ctx);
// EVP_DecodeUpdate decodes |in_len| bytes from |in| and writes the decoded
// data to |out| and sets |*out_len| to the number of bytes written. Some state
// may be contained in |ctx| so |EVP_DecodeFinal| must be used to flush it
// EVP_DecodeUpdate decodes `in_len` bytes from `in` and writes the decoded
// data to `out` and sets `*out_len` to the number of bytes written. Some state
// may be contained in `ctx` so `EVP_DecodeFinal` must be used to flush it
// before using the encoded data.
//
// It returns -1 on error, one if a full line of input was processed and zero
@@ -116,14 +116,14 @@ OPENSSL_EXPORT int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, uint8_t *out,
int *out_len, const uint8_t *in,
size_t in_len);
// EVP_DecodeFinal flushes any remaining output bytes from |ctx| to |out| and
// sets |*out_len| to the number of bytes written. It returns one on success
// EVP_DecodeFinal flushes any remaining output bytes from `ctx` to `out` and
// sets `*out_len` to the number of bytes written. It returns one on success
// and minus one on error.
OPENSSL_EXPORT int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, uint8_t *out,
int *out_len);
// EVP_DecodeBlock encodes |src_len| bytes from |src| and writes the result to
// |dst|. It returns the number of bytes written or -1 on error.
// EVP_DecodeBlock encodes `src_len` bytes from `src` and writes the result to
// `dst`. It returns the number of bytes written or -1 on error.
//
// WARNING: EVP_DecodeBlock's return value does not take padding into
// account. It also strips leading whitespace and trailing
@@ -133,9 +133,9 @@ OPENSSL_EXPORT int EVP_DecodeBlock(uint8_t *dst, const uint8_t *src,
struct evp_encode_ctx_st {
// data_used indicates the number of bytes of |data| that are valid. When
// encoding, |data| will be filled and encoded as a lump. When decoding, only
// the first four bytes of |data| will be used.
// data_used indicates the number of bytes of `data` that are valid. When
// encoding, `data` will be filled and encoded as a lump. When decoding, only
// the first four bytes of `data` will be used.
unsigned data_used;
uint8_t data[48];
include/openssl/bio.h
+273 -273
View File
File diff suppressed because it is too large Load Diff
include/openssl/blake2.h
+8 -8
View File
@@ -36,22 +36,22 @@ struct blake2b_state_st {
uint8_t block[BLAKE2B_CBLOCK];
};
// BLAKE2B256_Init initialises |b2b| to perform a BLAKE2b-256 hash. There are no
// pointers inside |b2b| thus release of |b2b| is purely managed by the caller.
// BLAKE2B256_Init initialises `b2b` to perform a BLAKE2b-256 hash. There are no
// pointers inside `b2b` thus release of `b2b` is purely managed by the caller.
OPENSSL_EXPORT void BLAKE2B256_Init(BLAKE2B_CTX *b2b);
// BLAKE2B256_Update appends |len| bytes from |data| to the digest being
// calculated by |b2b|.
// BLAKE2B256_Update appends `len` bytes from `data` to the digest being
// calculated by `b2b`.
OPENSSL_EXPORT void BLAKE2B256_Update(BLAKE2B_CTX *b2b, const void *data,
size_t len);
// BLAKE2B256_Final completes the digest calculated by |b2b| and writes
// |BLAKE2B256_DIGEST_LENGTH| bytes to |out|.
// BLAKE2B256_Final completes the digest calculated by `b2b` and writes
// `BLAKE2B256_DIGEST_LENGTH` bytes to `out`.
OPENSSL_EXPORT void BLAKE2B256_Final(uint8_t out[BLAKE2B256_DIGEST_LENGTH],
BLAKE2B_CTX *b2b);
// BLAKE2B256 writes the BLAKE2b-256 digset of |len| bytes from |data| to
// |out|.
// BLAKE2B256 writes the BLAKE2b-256 digset of `len` bytes from `data` to
// `out`.
OPENSSL_EXPORT void BLAKE2B256(const uint8_t *data, size_t len,
uint8_t out[BLAKE2B256_DIGEST_LENGTH]);
include/openssl/bn.h
+296 -296
View File
File diff suppressed because it is too large Load Diff
include/openssl/buf.h
+14 -14
View File
@@ -25,7 +25,7 @@ extern "C" {
// Memory and string functions, see also mem.h.
// buf_mem_st (aka |BUF_MEM|) is a generic buffer object used by OpenSSL.
// buf_mem_st (aka `BUF_MEM`) is a generic buffer object used by OpenSSL.
struct buf_mem_st {
size_t length; // current number of bytes
char *data;
@@ -35,45 +35,45 @@ struct buf_mem_st {
// BUF_MEM_new creates a new BUF_MEM which has no allocated data buffer.
OPENSSL_EXPORT BUF_MEM *BUF_MEM_new(void);
// BUF_MEM_free frees |buf->data| if needed and then frees |buf| itself.
// BUF_MEM_free frees `buf->data` if needed and then frees `buf` itself.
OPENSSL_EXPORT void BUF_MEM_free(BUF_MEM *buf);
// BUF_MEM_reserve ensures |buf| has capacity |cap| and allocates memory if
// BUF_MEM_reserve ensures `buf` has capacity `cap` and allocates memory if
// needed. It returns one on success and zero on error.
OPENSSL_EXPORT int BUF_MEM_reserve(BUF_MEM *buf, size_t cap);
// BUF_MEM_grow ensures that |buf| has length |len| and allocates memory if
// needed. If the length of |buf| increased, the new bytes are filled with
// zeros. It returns the length of |buf|, or zero if there's an error.
// BUF_MEM_grow ensures that `buf` has length `len` and allocates memory if
// needed. If the length of `buf` increased, the new bytes are filled with
// zeros. It returns the length of `buf`, or zero if there's an error.
OPENSSL_EXPORT size_t BUF_MEM_grow(BUF_MEM *buf, size_t len);
// BUF_MEM_grow_clean calls |BUF_MEM_grow|. BoringSSL always zeros memory
// BUF_MEM_grow_clean calls `BUF_MEM_grow`. BoringSSL always zeros memory
// allocated memory on free.
OPENSSL_EXPORT size_t BUF_MEM_grow_clean(BUF_MEM *buf, size_t len);
// BUF_MEM_append appends |in| to |buf|. It returns one on success and zero on
// BUF_MEM_append appends `in` to `buf`. It returns one on success and zero on
// error.
OPENSSL_EXPORT int BUF_MEM_append(BUF_MEM *buf, const void *in, size_t len);
// Deprecated functions.
// BUF_strdup calls |OPENSSL_strdup|.
// BUF_strdup calls `OPENSSL_strdup`.
OPENSSL_EXPORT char *BUF_strdup(const char *str);
// BUF_strnlen calls |OPENSSL_strnlen|.
// BUF_strnlen calls `OPENSSL_strnlen`.
OPENSSL_EXPORT size_t BUF_strnlen(const char *str, size_t max_len);
// BUF_strndup calls |OPENSSL_strndup|.
// BUF_strndup calls `OPENSSL_strndup`.
OPENSSL_EXPORT char *BUF_strndup(const char *str, size_t size);
// BUF_memdup calls |OPENSSL_memdup|.
// BUF_memdup calls `OPENSSL_memdup`.
OPENSSL_EXPORT void *BUF_memdup(const void *data, size_t size);
// BUF_strlcpy calls |OPENSSL_strlcpy|.
// BUF_strlcpy calls `OPENSSL_strlcpy`.
OPENSSL_EXPORT size_t BUF_strlcpy(char *dst, const char *src, size_t dst_size);
// BUF_strlcat calls |OPENSSL_strlcat|.
// BUF_strlcat calls `OPENSSL_strlcat`.
OPENSSL_EXPORT size_t BUF_strlcat(char *dst, const char *src, size_t dst_size);
include/openssl/bytestring.h
+226 -226
View File
@@ -54,148 +54,148 @@ struct cbs_st {
#endif
};
// CBS_init sets |cbs| to point to |data|. It does not take ownership of
// |data|.
// CBS_init sets `cbs` to point to `data`. It does not take ownership of
// `data`.
OPENSSL_INLINE void CBS_init(CBS *cbs, const uint8_t *data, size_t len) {
cbs->data = data;
cbs->len = len;
}
// CBS_skip advances |cbs| by |len| bytes. It returns one on success and zero
// CBS_skip advances `cbs` by `len` bytes. It returns one on success and zero
// otherwise.
OPENSSL_EXPORT int CBS_skip(CBS *cbs, size_t len);
// CBS_data returns a pointer to the contents of |cbs|.
// CBS_data returns a pointer to the contents of `cbs`.
OPENSSL_INLINE const uint8_t *CBS_data(const CBS *cbs) { return cbs->data; }
// CBS_len returns the number of bytes remaining in |cbs|.
// CBS_len returns the number of bytes remaining in `cbs`.
OPENSSL_INLINE size_t CBS_len(const CBS *cbs) { return cbs->len; }
// CBS_stow copies the current contents of |cbs| into |*out_ptr| and
// |*out_len|. If |*out_ptr| is not NULL, the contents are freed with
// CBS_stow copies the current contents of `cbs` into `*out_ptr` and
// `*out_len`. If `*out_ptr` is not NULL, the contents are freed with
// OPENSSL_free. It returns one on success and zero on allocation failure. On
// success, |*out_ptr| should be freed with OPENSSL_free. If |cbs| is empty,
// |*out_ptr| will be NULL.
// success, `*out_ptr` should be freed with OPENSSL_free. If `cbs` is empty,
// `*out_ptr` will be NULL.
OPENSSL_EXPORT int CBS_stow(const CBS *cbs, uint8_t **out_ptr, size_t *out_len);
// CBS_strdup copies the current contents of |cbs| into |*out_ptr| as a
// NUL-terminated C string. If |*out_ptr| is not NULL, the contents are freed
// CBS_strdup copies the current contents of `cbs` into `*out_ptr` as a
// NUL-terminated C string. If `*out_ptr` is not NULL, the contents are freed
// with OPENSSL_free. It returns one on success and zero on allocation
// failure. On success, |*out_ptr| should be freed with OPENSSL_free.
// failure. On success, `*out_ptr` should be freed with OPENSSL_free.
//
// NOTE: If |cbs| contains NUL bytes, the string will be truncated. Call
// |CBS_contains_zero_byte(cbs)| to check for NUL bytes.
// NOTE: If `cbs` contains NUL bytes, the string will be truncated. Call
// `CBS_contains_zero_byte(cbs)` to check for NUL bytes.
OPENSSL_EXPORT int CBS_strdup(const CBS *cbs, char **out_ptr);
// CBS_contains_zero_byte returns one if the current contents of |cbs| contains
// CBS_contains_zero_byte returns one if the current contents of `cbs` contains
// a NUL byte and zero otherwise.
OPENSSL_EXPORT int CBS_contains_zero_byte(const CBS *cbs);
// CBS_mem_equal compares the current contents of |cbs| with the |len| bytes
// starting at |data|. If they're equal, it returns one, otherwise zero. If the
// CBS_mem_equal compares the current contents of `cbs` with the `len` bytes
// starting at `data`. If they're equal, it returns one, otherwise zero. If the
// lengths match, it uses a constant-time comparison.
OPENSSL_EXPORT int CBS_mem_equal(const CBS *cbs, const uint8_t *data,
size_t len);
// CBS_get_u8 sets |*out| to the next uint8_t from |cbs| and advances |cbs|. It
// CBS_get_u8 sets `*out` to the next uint8_t from `cbs` and advances `cbs`. It
// returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u8(CBS *cbs, uint8_t *out);
// CBS_get_u16 sets |*out| to the next, big-endian uint16_t from |cbs| and
// advances |cbs|. It returns one on success and zero on error.
// CBS_get_u16 sets `*out` to the next, big-endian uint16_t from `cbs` and
// advances `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u16(CBS *cbs, uint16_t *out);
// CBS_get_u16le sets |*out| to the next, little-endian uint16_t from |cbs| and
// advances |cbs|. It returns one on success and zero on error.
// CBS_get_u16le sets `*out` to the next, little-endian uint16_t from `cbs` and
// advances `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u16le(CBS *cbs, uint16_t *out);
// CBS_get_u24 sets |*out| to the next, big-endian 24-bit value from |cbs| and
// advances |cbs|. It returns one on success and zero on error.
// CBS_get_u24 sets `*out` to the next, big-endian 24-bit value from `cbs` and
// advances `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u24(CBS *cbs, uint32_t *out);
// CBS_get_u32 sets |*out| to the next, big-endian uint32_t value from |cbs|
// and advances |cbs|. It returns one on success and zero on error.
// CBS_get_u32 sets `*out` to the next, big-endian uint32_t value from `cbs`
// and advances `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u32(CBS *cbs, uint32_t *out);
// CBS_get_u32le sets |*out| to the next, little-endian uint32_t value from
// |cbs| and advances |cbs|. It returns one on success and zero on error.
// CBS_get_u32le sets `*out` to the next, little-endian uint32_t value from
// `cbs` and advances `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u32le(CBS *cbs, uint32_t *out);
// CBS_get_u48 sets |*out| to the next, big-endian 48-bit value from |cbs| and
// advances |cbs|. It returns one on success and zero on error.
// CBS_get_u48 sets `*out` to the next, big-endian 48-bit value from `cbs` and
// advances `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u48(CBS *cbs, uint64_t *out);
// CBS_get_u64 sets |*out| to the next, big-endian uint64_t value from |cbs|
// and advances |cbs|. It returns one on success and zero on error.
// CBS_get_u64 sets `*out` to the next, big-endian uint64_t value from `cbs`
// and advances `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u64(CBS *cbs, uint64_t *out);
// CBS_get_u64le sets |*out| to the next, little-endian uint64_t value from
// |cbs| and advances |cbs|. It returns one on success and zero on error.
// CBS_get_u64le sets `*out` to the next, little-endian uint64_t value from
// `cbs` and advances `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u64le(CBS *cbs, uint64_t *out);
// CBS_get_last_u8 sets |*out| to the last uint8_t from |cbs| and shortens
// |cbs|. It returns one on success and zero on error.
// CBS_get_last_u8 sets `*out` to the last uint8_t from `cbs` and shortens
// `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_last_u8(CBS *cbs, uint8_t *out);
// CBS_get_bytes sets |*out| to the next |len| bytes from |cbs| and advances
// |cbs|. It returns one on success and zero on error.
// CBS_get_bytes sets `*out` to the next `len` bytes from `cbs` and advances
// `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_bytes(CBS *cbs, CBS *out, size_t len);
// CBS_copy_bytes copies the next |len| bytes from |cbs| to |out| and advances
// |cbs|. It returns one on success and zero on error.
// CBS_copy_bytes copies the next `len` bytes from `cbs` to `out` and advances
// `cbs`. It returns one on success and zero on error.
OPENSSL_EXPORT int CBS_copy_bytes(CBS *cbs, uint8_t *out, size_t len);
// CBS_get_u8_length_prefixed sets |*out| to the contents of an 8-bit,
// length-prefixed value from |cbs| and advances |cbs| over it. It returns one
// CBS_get_u8_length_prefixed sets `*out` to the contents of an 8-bit,
// length-prefixed value from `cbs` and advances `cbs` over it. It returns one
// on success and zero on error.
OPENSSL_EXPORT int CBS_get_u8_length_prefixed(CBS *cbs, CBS *out);
// CBS_get_u16_length_prefixed sets |*out| to the contents of a 16-bit,
// big-endian, length-prefixed value from |cbs| and advances |cbs| over it. It
// CBS_get_u16_length_prefixed sets `*out` to the contents of a 16-bit,
// big-endian, length-prefixed value from `cbs` and advances `cbs` over it. It
// returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u16_length_prefixed(CBS *cbs, CBS *out);
// CBS_get_u24_length_prefixed sets |*out| to the contents of a 24-bit,
// big-endian, length-prefixed value from |cbs| and advances |cbs| over it. It
// CBS_get_u24_length_prefixed sets `*out` to the contents of a 24-bit,
// big-endian, length-prefixed value from `cbs` and advances `cbs` over it. It
// returns one on success and zero on error.
OPENSSL_EXPORT int CBS_get_u24_length_prefixed(CBS *cbs, CBS *out);
// CBS_get_until_first finds the first instance of |c| in |cbs|. If found, it
// sets |*out| to the text before the match, advances |cbs| over it, and returns
// one. Otherwise, it returns zero and leaves |cbs| unmodified.
// CBS_get_until_first finds the first instance of `c` in `cbs`. If found, it
// sets `*out` to the text before the match, advances `cbs` over it, and returns
// one. Otherwise, it returns zero and leaves `cbs` unmodified.
OPENSSL_EXPORT int CBS_get_until_first(CBS *cbs, CBS *out, uint8_t c);
// CBS_get_until_first_of finds the first byte in |cbs| matching one of the
// characters in |chars|, which is a NUL-terminated C string. If found, it sets
// |*out| to the text before the match, advances |cbs| over it, and returns one.
// Otherwise, it returns zero and leaves |cbs| unmodified.
// CBS_get_until_first_of finds the first byte in `cbs` matching one of the
// characters in `chars`, which is a NUL-terminated C string. If found, it sets
// `*out` to the text before the match, advances `cbs` over it, and returns one.
// Otherwise, it returns zero and leaves `cbs` unmodified.
OPENSSL_EXPORT int CBS_get_until_first_of(CBS *cbs, CBS *out,
const char *chars);
// CBS_get_until_first_not_of finds the first byte in |cbs| that does not match
// any of the characters in |chars|, which is a NUL-terminated C string. If
// found, it sets |*out| to the text before the match, advances |cbs| over it,
// and returns one. Otherwise, it returns zero and leaves |cbs| unmodified.
// CBS_get_until_first_not_of finds the first byte in `cbs` that does not match
// any of the characters in `chars`, which is a NUL-terminated C string. If
// found, it sets `*out` to the text before the match, advances `cbs` over it,
// and returns one. Otherwise, it returns zero and leaves `cbs` unmodified.
OPENSSL_EXPORT int CBS_get_until_first_not_of(CBS *cbs, CBS *out,
const char *chars);
// CBS_get_u64_decimal reads a decimal integer from |cbs| and writes it to
// |*out|. It stops reading at the end of the string, or the first non-digit
// CBS_get_u64_decimal reads a decimal integer from `cbs` and writes it to
// `*out`. It stops reading at the end of the string, or the first non-digit
// character. It returns one on success and zero on error. This function behaves
// analogously to |strtoul| except it does not accept empty inputs, leading
// analogously to `strtoul` except it does not accept empty inputs, leading
// zeros, or negative values.
OPENSSL_EXPORT int CBS_get_u64_decimal(CBS *cbs, uint64_t *out);
// Parsing ASN.1
//
// |CBS| may be used to parse DER structures. Rather than using a schema
// `CBS` may be used to parse DER structures. Rather than using a schema
// compiler, the following functions act on tag-length-value elements in the
// serialization itself. Thus the caller is responsible for looping over a
// SEQUENCE, branching on CHOICEs or OPTIONAL fields, checking for trailing
// data, and handling explicit vs. implicit tagging.
//
// Tags are represented as |CBS_ASN1_TAG| values in memory. The upper few bits
// Tags are represented as `CBS_ASN1_TAG` values in memory. The upper few bits
// store the class and constructed bit, and the remaining bits store the tag
// number. Note this differs from the DER serialization, to support tag numbers
// beyond 31. Consumers must use the constants defined below to decompose or
@@ -253,46 +253,46 @@ OPENSSL_EXPORT int CBS_get_u64_decimal(CBS *cbs, uint64_t *out);
#define CBS_ASN1_UNIVERSALSTRING 0x1cu
#define CBS_ASN1_BMPSTRING 0x1eu
// CBS_get_asn1 sets |*out| to the contents of DER-encoded, ASN.1 element (not
// including tag and length bytes) and advances |cbs| over it. The ASN.1
// element must match |tag_value|. It returns one on success and zero
// CBS_get_asn1 sets `*out` to the contents of DER-encoded, ASN.1 element (not
// including tag and length bytes) and advances `cbs` over it. The ASN.1
// element must match `tag_value`. It returns one on success and zero
// on error.
OPENSSL_EXPORT int CBS_get_asn1(CBS *cbs, CBS *out, CBS_ASN1_TAG tag_value);
// CBS_get_asn1_element acts like |CBS_get_asn1| but |out| will include the
// CBS_get_asn1_element acts like `CBS_get_asn1` but `out` will include the
// ASN.1 header bytes too.
OPENSSL_EXPORT int CBS_get_asn1_element(CBS *cbs, CBS *out,
CBS_ASN1_TAG tag_value);
// CBS_peek_asn1_tag looks ahead at the next ASN.1 tag and returns one
// if the next ASN.1 element on |cbs| would have tag |tag_value|. If
// |cbs| is empty or the tag does not match, it returns zero. Note: if
// if the next ASN.1 element on `cbs` would have tag `tag_value`. If
// `cbs` is empty or the tag does not match, it returns zero. Note: if
// it returns one, CBS_get_asn1 may still fail if the rest of the
// element is malformed.
OPENSSL_EXPORT int CBS_peek_asn1_tag(const CBS *cbs, CBS_ASN1_TAG tag_value);
// CBS_get_any_asn1 sets |*out| to contain the next ASN.1 element from |*cbs|
// (not including tag and length bytes), sets |*out_tag| to the tag number, and
// advances |*cbs|. It returns one on success and zero on error. Either of |out|
// and |out_tag| may be NULL to ignore the value.
// CBS_get_any_asn1 sets `*out` to contain the next ASN.1 element from `*cbs`
// (not including tag and length bytes), sets `*out_tag` to the tag number, and
// advances `*cbs`. It returns one on success and zero on error. Either of `out`
// and `out_tag` may be NULL to ignore the value.
OPENSSL_EXPORT int CBS_get_any_asn1(CBS *cbs, CBS *out,
CBS_ASN1_TAG *out_tag);
// CBS_get_any_asn1_element sets |*out| to contain the next ASN.1 element from
// |*cbs| (including header bytes) and advances |*cbs|. It sets |*out_tag| to
// the tag number and |*out_header_len| to the length of the ASN.1 header. Each
// of |out|, |out_tag|, and |out_header_len| may be NULL to ignore the value.
// CBS_get_any_asn1_element sets `*out` to contain the next ASN.1 element from
// `*cbs` (including header bytes) and advances `*cbs`. It sets `*out_tag` to
// the tag number and `*out_header_len` to the length of the ASN.1 header. Each
// of `out`, `out_tag`, and `out_header_len` may be NULL to ignore the value.
OPENSSL_EXPORT int CBS_get_any_asn1_element(CBS *cbs, CBS *out,
CBS_ASN1_TAG *out_tag,
size_t *out_header_len);
// CBS_get_any_ber_asn1_element acts the same as |CBS_get_any_asn1_element| but
// CBS_get_any_ber_asn1_element acts the same as `CBS_get_any_asn1_element` but
// also allows indefinite-length elements to be returned and does not enforce
// that lengths are minimal. It sets |*out_indefinite| to one if the length was
// indefinite and zero otherwise. If indefinite, |*out_header_len| and
// |CBS_len(out)| will be equal as only the header is returned (although this is
// also true for empty elements so |*out_indefinite| should be checked). If
// |out_ber_found| is not NULL then it is set to one if any case of invalid DER
// that lengths are minimal. It sets `*out_indefinite` to one if the length was
// indefinite and zero otherwise. If indefinite, `*out_header_len` and
// `CBS_len(out)` will be equal as only the header is returned (although this is
// also true for empty elements so `*out_indefinite` should be checked). If
// `out_ber_found` is not NULL then it is set to one if any case of invalid DER
// but valid BER is found, and to zero otherwise.
//
// This function will not successfully parse an end-of-contents (EOC) as an
@@ -304,14 +304,14 @@ OPENSSL_EXPORT int CBS_get_any_ber_asn1_element(CBS *cbs, CBS *out,
int *out_ber_found,
int *out_indefinite);
// CBS_get_asn1_uint64 gets an ASN.1 INTEGER from |cbs| using |CBS_get_asn1|
// and sets |*out| to its value. It returns one on success and zero on error,
// CBS_get_asn1_uint64 gets an ASN.1 INTEGER from `cbs` using `CBS_get_asn1`
// and sets `*out` to its value. It returns one on success and zero on error,
// where error includes the integer being negative, or too large to represent
// in 64 bits.
OPENSSL_EXPORT int CBS_get_asn1_uint64(CBS *cbs, uint64_t *out);
// CBS_get_asn1_uint64_with_tag gets an ASN.1 INTEGER from |cbs| using
// |CBS_get_asn1| and sets |*out| to its value. |tag| is used to handle to
// CBS_get_asn1_uint64_with_tag gets an ASN.1 INTEGER from `cbs` using
// `CBS_get_asn1` and sets `*out` to its value. `tag` is used to handle to
// handle implicitly tagged INTEGER fields. It returns one on success and zero
// on error, where error includes the integer being negative, or too large to
// represent in 64 bits.
@@ -319,35 +319,35 @@ OPENSSL_EXPORT int CBS_get_asn1_uint64_with_tag(CBS *cbs, uint64_t *out,
CBS_ASN1_TAG tag);
// CBS_get_asn1_int64 gets an ASN.1 INTEGER from |cbs| using |CBS_get_asn1|
// and sets |*out| to its value. It returns one on success and zero on error,
// CBS_get_asn1_int64 gets an ASN.1 INTEGER from `cbs` using `CBS_get_asn1`
// and sets `*out` to its value. It returns one on success and zero on error,
// where error includes the integer being too large to represent in 64 bits.
OPENSSL_EXPORT int CBS_get_asn1_int64(CBS *cbs, int64_t *out);
// CBS_get_asn1_int64_with_tag gets an ASN.1 INTEGER from |cbs| using
// |CBS_get_asn1| and sets |*out| to its value. |tag| is used to handle to
// CBS_get_asn1_int64_with_tag gets an ASN.1 INTEGER from `cbs` using
// `CBS_get_asn1` and sets `*out` to its value. `tag` is used to handle to
// handle implicitly tagged INTEGER fields. It returns one on success and zero
// on error, where error includes the integer being too large to represent in 64
// bits.
OPENSSL_EXPORT int CBS_get_asn1_int64_with_tag(CBS *cbs, int64_t *out,
CBS_ASN1_TAG tag);
// CBS_get_asn1_bool gets an ASN.1 BOOLEAN from |cbs| and sets |*out| to zero
// CBS_get_asn1_bool gets an ASN.1 BOOLEAN from `cbs` and sets `*out` to zero
// or one based on its value. It returns one on success or zero on error.
OPENSSL_EXPORT int CBS_get_asn1_bool(CBS *cbs, int *out);
// CBS_get_optional_asn1 gets an optional explicitly-tagged element from |cbs|
// tagged with |tag| and sets |*out| to its contents, or ignores it if |out| is
// NULL. If present and if |out_present| is not NULL, it sets |*out_present| to
// CBS_get_optional_asn1 gets an optional explicitly-tagged element from `cbs`
// tagged with `tag` and sets `*out` to its contents, or ignores it if `out` is
// NULL. If present and if `out_present` is not NULL, it sets `*out_present` to
// one, otherwise zero. It returns one on success, whether or not the element
// was present, and zero on decode failure.
OPENSSL_EXPORT int CBS_get_optional_asn1(CBS *cbs, CBS *out, int *out_present,
CBS_ASN1_TAG tag);
// CBS_get_optional_asn1_octet_string gets an optional
// explicitly-tagged OCTET STRING from |cbs|. If present, it sets
// |*out| to the string and |*out_present| to one. Otherwise, it sets
// |*out| to empty and |*out_present| to zero. |out_present| may be
// explicitly-tagged OCTET STRING from `cbs`. If present, it sets
// `*out` to the string and `*out_present` to one. Otherwise, it sets
// `*out` to empty and `*out_present` to zero. `out_present` may be
// NULL. It returns one on success, whether or not the element was
// present, and zero on decode failure.
OPENSSL_EXPORT int CBS_get_optional_asn1_octet_string(CBS *cbs, CBS *out,
@@ -355,8 +355,8 @@ OPENSSL_EXPORT int CBS_get_optional_asn1_octet_string(CBS *cbs, CBS *out,
CBS_ASN1_TAG tag);
// CBS_get_optional_asn1_uint64 gets an optional explicitly-tagged
// INTEGER from |cbs|. If present, it sets |*out| to the
// value. Otherwise, it sets |*out| to |default_value|. It returns one
// INTEGER from `cbs`. If present, it sets `*out` to the
// value. Otherwise, it sets `*out` to `default_value`. It returns one
// on success, whether or not the element was present, and zero on
// decode failure.
OPENSSL_EXPORT int CBS_get_optional_asn1_uint64(CBS *cbs, uint64_t *out,
@@ -364,108 +364,108 @@ OPENSSL_EXPORT int CBS_get_optional_asn1_uint64(CBS *cbs, uint64_t *out,
uint64_t default_value);
// CBS_get_optional_asn1_bool gets an optional, explicitly-tagged BOOLEAN from
// |cbs|. If present, it sets |*out| to either zero or one, based on the
// boolean. Otherwise, it sets |*out| to |default_value|. It returns one on
// `cbs`. If present, it sets `*out` to either zero or one, based on the
// boolean. Otherwise, it sets `*out` to `default_value`. It returns one on
// success, whether or not the element was present, and zero on decode
// failure.
OPENSSL_EXPORT int CBS_get_optional_asn1_bool(CBS *cbs, int *out,
CBS_ASN1_TAG tag,
int default_value);
// CBS_is_valid_asn1_bitstring returns one if |cbs| is a valid ASN.1 BIT STRING
// CBS_is_valid_asn1_bitstring returns one if `cbs` is a valid ASN.1 BIT STRING
// body and zero otherwise.
OPENSSL_EXPORT int CBS_is_valid_asn1_bitstring(const CBS *cbs);
// CBS_asn1_bitstring_has_bit returns one if |cbs| is a valid ASN.1 BIT STRING
// CBS_asn1_bitstring_has_bit returns one if `cbs` is a valid ASN.1 BIT STRING
// body and the specified bit is present and set. Otherwise, it returns zero.
// |bit| is indexed starting from zero.
// `bit` is indexed starting from zero.
OPENSSL_EXPORT int CBS_asn1_bitstring_has_bit(const CBS *cbs, unsigned bit);
// CBS_is_valid_asn1_integer returns one if |cbs| is a valid ASN.1 INTEGER,
// body and zero otherwise. On success, if |out_is_negative| is non-NULL,
// |*out_is_negative| will be set to one if |cbs| is negative and zero
// CBS_is_valid_asn1_integer returns one if `cbs` is a valid ASN.1 INTEGER,
// body and zero otherwise. On success, if `out_is_negative` is non-NULL,
// `*out_is_negative` will be set to one if `cbs` is negative and zero
// otherwise.
OPENSSL_EXPORT int CBS_is_valid_asn1_integer(const CBS *cbs,
int *out_is_negative);
// CBS_is_unsigned_asn1_integer returns one if |cbs| is a valid non-negative
// CBS_is_unsigned_asn1_integer returns one if `cbs` is a valid non-negative
// ASN.1 INTEGER body and zero otherwise.
OPENSSL_EXPORT int CBS_is_unsigned_asn1_integer(const CBS *cbs);
// CBS_is_valid_asn1_oid returns one if |cbs| is a valid DER-encoded ASN.1
// CBS_is_valid_asn1_oid returns one if `cbs` is a valid DER-encoded ASN.1
// OBJECT IDENTIFIER contents (not including the element framing) and zero
// otherwise. This function tolerates arbitrarily large OID components.
OPENSSL_EXPORT int CBS_is_valid_asn1_oid(const CBS *cbs);
// CBS_asn1_oid_to_text interprets |cbs| as DER-encoded ASN.1 OBJECT IDENTIFIER
// CBS_asn1_oid_to_text interprets `cbs` as DER-encoded ASN.1 OBJECT IDENTIFIER
// contents (not including the element framing) and returns the ASCII
// representation (e.g., "1.2.840.113554.4.1.72585") in a newly-allocated
// string, or NULL on failure. The caller must release the result with
// |OPENSSL_free|.
// `OPENSSL_free`.
//
// This function may fail if |cbs| is an invalid OBJECT IDENTIFIER, or if any
// This function may fail if `cbs` is an invalid OBJECT IDENTIFIER, or if any
// OID components are too large.
OPENSSL_EXPORT char *CBS_asn1_oid_to_text(const CBS *cbs);
// CBS_is_valid_asn1_relative_oid returns one if |cbs| is a valid DER-encoded
// CBS_is_valid_asn1_relative_oid returns one if `cbs` is a valid DER-encoded
// ASN.1 RELATIVE-OID contents (not including the element framing) and zero
// otherwise. This function tolerates arbitrarily large OID components.
//
// (This is actually the same as |CBS_is_valid_asn1_oid|, but is also exposed
// (This is actually the same as `CBS_is_valid_asn1_oid`, but is also exposed
// under the relative_oid name for API symmetry.)
OPENSSL_EXPORT int CBS_is_valid_asn1_relative_oid(const CBS *cbs);
// CBS_asn1_relative_oid_to_text interprets |cbs| as DER-encoded ASN.1
// CBS_asn1_relative_oid_to_text interprets `cbs` as DER-encoded ASN.1
// RELATIVE-OID contents (not including the element framing) and returns the
// ASCII representation (e.g., "32473.1") in a newly-allocated string, or NULL
// on failure. The caller must release the result with |OPENSSL_free|.
// on failure. The caller must release the result with `OPENSSL_free`.
//
// This function may fail if |cbs| is an invalid RELATIVE-OID, or if any
// This function may fail if `cbs` is an invalid RELATIVE-OID, or if any
// OID components are too large.
OPENSSL_EXPORT char *CBS_asn1_relative_oid_to_text(const CBS *cbs);
// CBS_parse_generalized_time returns one if |cbs| is a valid DER-encoded, ASN.1
// CBS_parse_generalized_time returns one if `cbs` is a valid DER-encoded, ASN.1
// GeneralizedTime body within the limitations imposed by RFC 5280, or zero
// otherwise. If |allow_timezone_offset| is non-zero, four-digit timezone
// otherwise. If `allow_timezone_offset` is non-zero, four-digit timezone
// offsets, which would not be allowed by DER, are permitted. On success, if
// |out_tm| is non-NULL, |*out_tm| will be zeroed, and then set to the
// corresponding time in UTC. This function does not compute |out_tm->tm_wday|
// or |out_tm->tm_yday|.
// `out_tm` is non-NULL, `*out_tm` will be zeroed, and then set to the
// corresponding time in UTC. This function does not compute `out_tm->tm_wday`
// or `out_tm->tm_yday`.
OPENSSL_EXPORT int CBS_parse_generalized_time(const CBS *cbs, struct tm *out_tm,
int allow_timezone_offset);
// CBS_parse_utc_time returns one if |cbs| is a valid DER-encoded, ASN.1
// CBS_parse_utc_time returns one if `cbs` is a valid DER-encoded, ASN.1
// UTCTime body within the limitations imposed by RFC 5280, or zero otherwise.
// If |allow_timezone_offset| is non-zero, four-digit timezone offsets, which
// would not be allowed by DER, are permitted. On success, if |out_tm| is
// non-NULL, |*out_tm| will be zeroed, and then set to the corresponding time
// in UTC. This function does not compute |out_tm->tm_wday| or
// |out_tm->tm_yday|.
// If `allow_timezone_offset` is non-zero, four-digit timezone offsets, which
// would not be allowed by DER, are permitted. On success, if `out_tm` is
// non-NULL, `*out_tm` will be zeroed, and then set to the corresponding time
// in UTC. This function does not compute `out_tm->tm_wday` or
// `out_tm->tm_yday`.
OPENSSL_EXPORT int CBS_parse_utc_time(const CBS *cbs, struct tm *out_tm,
int allow_timezone_offset);
// CRYPTO ByteBuilder.
//
// |CBB| objects allow one to build length-prefixed serialisations. A |CBB|
// `CBB` objects allow one to build length-prefixed serialisations. A `CBB`
// object is associated with a buffer and new buffers are created with
// |CBB_init|. Several |CBB| objects can point at the same buffer when a
// length-prefix is pending, however only a single |CBB| can be 'current' at
// any one time. For example, if one calls |CBB_add_u8_length_prefixed| then
// the new |CBB| points at the same buffer as the original. But if the original
// |CBB| is used then the length prefix is written out and the new |CBB| must
// `CBB_init`. Several `CBB` objects can point at the same buffer when a
// length-prefix is pending, however only a single `CBB` can be 'current' at
// any one time. For example, if one calls `CBB_add_u8_length_prefixed` then
// the new `CBB` points at the same buffer as the original. But if the original
// `CBB` is used then the length prefix is written out and the new `CBB` must
// not be used again.
//
// If one needs to force a length prefix to be written out because a |CBB| is
// going out of scope, use |CBB_flush|. If an operation on a |CBB| fails, it is
// in an undefined state and must not be used except to call |CBB_cleanup|.
// If one needs to force a length prefix to be written out because a `CBB` is
// going out of scope, use `CBB_flush`. If an operation on a `CBB` fails, it is
// in an undefined state and must not be used except to call `CBB_cleanup`.
struct cbb_buffer_st {
uint8_t *buf;
// len is the number of valid bytes in |buf|.
// len is the number of valid bytes in `buf`.
size_t len;
// cap is the size of |buf|.
// cap is the size of `buf`.
size_t cap;
// can_resize is one iff |buf| is owned by this object. If not then |buf|
// can_resize is one iff `buf` is owned by this object. If not then `buf`
// cannot be resized.
unsigned can_resize : 1;
// error is one if there was an error writing to this CBB. All future
@@ -474,12 +474,12 @@ struct cbb_buffer_st {
};
struct cbb_child_st {
// base is a pointer to the buffer this |CBB| writes to.
// base is a pointer to the buffer this `CBB` writes to.
struct cbb_buffer_st *base;
// offset is the number of bytes from the start of |base->buf| to this |CBB|'s
// offset is the number of bytes from the start of `base->buf` to this `CBB`'s
// pending length prefix.
size_t offset;
// pending_len_len contains the number of bytes in this |CBB|'s pending
// pending_len_len contains the number of bytes in this `CBB`'s pending
// length-prefix, or zero if no length-prefix is pending.
uint8_t pending_len_len;
unsigned pending_is_asn1 : 1;
@@ -488,8 +488,8 @@ struct cbb_child_st {
struct cbb_st {
// child points to a child CBB if a length-prefix is pending.
CBB *child;
// is_child is one if this is a child |CBB| and zero if it is a top-level
// |CBB|. This determines which arm of the union is valid.
// is_child is one if this is a child `CBB` and zero if it is a top-level
// `CBB`. This determines which arm of the union is valid.
char is_child;
union {
struct cbb_buffer_st base;
@@ -497,213 +497,213 @@ struct cbb_st {
} u;
};
// CBB_zero sets an uninitialised |cbb| to the zero state. It must be
// initialised with |CBB_init| or |CBB_init_fixed| before use, but it is safe to
// call |CBB_cleanup| without a successful |CBB_init|. This may be used for more
// uniform cleanup of a |CBB|.
// CBB_zero sets an uninitialised `cbb` to the zero state. It must be
// initialised with `CBB_init` or `CBB_init_fixed` before use, but it is safe to
// call `CBB_cleanup` without a successful `CBB_init`. This may be used for more
// uniform cleanup of a `CBB`.
OPENSSL_EXPORT void CBB_zero(CBB *cbb);
// CBB_init initialises |cbb| with |initial_capacity|. Since a |CBB| grows as
// needed, the |initial_capacity| is just a hint. It returns one on success or
// CBB_init initialises `cbb` with `initial_capacity`. Since a `CBB` grows as
// needed, the `initial_capacity` is just a hint. It returns one on success or
// zero on allocation failure.
OPENSSL_EXPORT int CBB_init(CBB *cbb, size_t initial_capacity);
// CBB_init_fixed initialises |cbb| to write to |len| bytes at |buf|. Since
// |buf| cannot grow, trying to write more than |len| bytes will cause CBB
// CBB_init_fixed initialises `cbb` to write to `len` bytes at `buf`. Since
// `buf` cannot grow, trying to write more than `len` bytes will cause CBB
// functions to fail. This function is infallible and always returns one. It is
// safe, but not necessary, to call |CBB_cleanup| on |cbb|.
// safe, but not necessary, to call `CBB_cleanup` on `cbb`.
OPENSSL_EXPORT int CBB_init_fixed(CBB *cbb, uint8_t *buf, size_t len);
// CBB_cleanup frees all resources owned by |cbb| and other |CBB| objects
// CBB_cleanup frees all resources owned by `cbb` and other `CBB` objects
// writing to the same buffer. This should be used in an error case where a
// serialisation is abandoned.
//
// This function can only be called on a "top level" |CBB|, i.e. one initialised
// with |CBB_init| or |CBB_init_fixed|, or a |CBB| set to the zero state with
// |CBB_zero|.
// This function can only be called on a "top level" `CBB`, i.e. one initialised
// with `CBB_init` or `CBB_init_fixed`, or a `CBB` set to the zero state with
// `CBB_zero`.
OPENSSL_EXPORT void CBB_cleanup(CBB *cbb);
// CBB_finish completes any pending length prefix and sets |*out_data| to a
// malloced buffer and |*out_len| to the length of that buffer. The caller
// CBB_finish completes any pending length prefix and sets `*out_data` to a
// malloced buffer and `*out_len` to the length of that buffer. The caller
// takes ownership of the buffer and, unless the buffer was fixed with
// |CBB_init_fixed|, must call |OPENSSL_free| when done.
// `CBB_init_fixed`, must call `OPENSSL_free` when done.
//
// It can only be called on a "top level" |CBB|, i.e. one initialised with
// |CBB_init| or |CBB_init_fixed|. It returns one on success and zero on
// It can only be called on a "top level" `CBB`, i.e. one initialised with
// `CBB_init` or `CBB_init_fixed`. It returns one on success and zero on
// error.
OPENSSL_EXPORT int CBB_finish(CBB *cbb, uint8_t **out_data, size_t *out_len);
// CBB_flush causes any pending length prefixes to be written out and any child
// |CBB| objects of |cbb| to be invalidated. This allows |cbb| to continue to be
// used after the children go out of scope, e.g. when local |CBB| objects are
// added as children to a |CBB| that persists after a function returns. This
// `CBB` objects of `cbb` to be invalidated. This allows `cbb` to continue to be
// used after the children go out of scope, e.g. when local `CBB` objects are
// added as children to a `CBB` that persists after a function returns. This
// function returns one on success or zero on error.
OPENSSL_EXPORT int CBB_flush(CBB *cbb);
// CBB_data returns a pointer to the bytes written to |cbb|. It does not flush
// |cbb|. The pointer is valid until the next operation to |cbb|.
// CBB_data returns a pointer to the bytes written to `cbb`. It does not flush
// `cbb`. The pointer is valid until the next operation to `cbb`.
//
// To avoid unfinalized length prefixes, it is a fatal error to call this on a
// CBB with any active children.
OPENSSL_EXPORT uint8_t *CBB_data(const CBB *cbb);
// CBB_len returns the number of bytes written to |cbb|. It does not flush
// |cbb|.
// CBB_len returns the number of bytes written to `cbb`. It does not flush
// `cbb`.
//
// To avoid unfinalized length prefixes, it is a fatal error to call this on a
// CBB with any active children.
OPENSSL_EXPORT size_t CBB_len(const CBB *cbb);
// CBB_add_u8_length_prefixed sets |*out_contents| to a new child of |cbb|. The
// data written to |*out_contents| will be prefixed in |cbb| with an 8-bit
// CBB_add_u8_length_prefixed sets `*out_contents` to a new child of `cbb`. The
// data written to `*out_contents` will be prefixed in `cbb` with an 8-bit
// length. It returns one on success or zero on error.
OPENSSL_EXPORT int CBB_add_u8_length_prefixed(CBB *cbb, CBB *out_contents);
// CBB_add_u16_length_prefixed sets |*out_contents| to a new child of |cbb|.
// The data written to |*out_contents| will be prefixed in |cbb| with a 16-bit,
// CBB_add_u16_length_prefixed sets `*out_contents` to a new child of `cbb`.
// The data written to `*out_contents` will be prefixed in `cbb` with a 16-bit,
// big-endian length. It returns one on success or zero on error.
OPENSSL_EXPORT int CBB_add_u16_length_prefixed(CBB *cbb, CBB *out_contents);
// CBB_add_u24_length_prefixed sets |*out_contents| to a new child of |cbb|.
// The data written to |*out_contents| will be prefixed in |cbb| with a 24-bit,
// CBB_add_u24_length_prefixed sets `*out_contents` to a new child of `cbb`.
// The data written to `*out_contents` will be prefixed in `cbb` with a 24-bit,
// big-endian length. It returns one on success or zero on error.
OPENSSL_EXPORT int CBB_add_u24_length_prefixed(CBB *cbb, CBB *out_contents);
// CBB_add_asn1 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
// CBB_add_asn1 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, CBS_ASN1_TAG tag);
// CBB_add_bytes appends |len| bytes from |data| to |cbb|. It returns one on
// CBB_add_bytes appends `len` bytes from `data` to `cbb`. It returns one on
// success and zero otherwise.
OPENSSL_EXPORT int CBB_add_bytes(CBB *cbb, const uint8_t *data, size_t len);
// CBB_add_zeros append |len| bytes with value zero to |cbb|. It returns one on
// CBB_add_zeros append `len` bytes with value zero to `cbb`. It returns one on
// success and zero otherwise.
OPENSSL_EXPORT int CBB_add_zeros(CBB *cbb, size_t len);
// CBB_add_space appends |len| bytes to |cbb| and sets |*out_data| to point to
// the beginning of that space. The caller must then write |len| bytes of
// actual contents to |*out_data|. It returns one on success and zero
// CBB_add_space appends `len` bytes to `cbb` and sets `*out_data` to point to
// the beginning of that space. The caller must then write `len` bytes of
// actual contents to `*out_data`. It returns one on success and zero
// otherwise.
OPENSSL_EXPORT int CBB_add_space(CBB *cbb, uint8_t **out_data, size_t len);
// CBB_reserve ensures |cbb| has room for |len| additional bytes and sets
// |*out_data| to point to the beginning of that space. It returns one on
// success and zero otherwise. The caller may write up to |len| bytes to
// |*out_data| and call |CBB_did_write| to complete the write. |*out_data| is
// valid until the next operation on |cbb| or an ancestor |CBB|.
// CBB_reserve ensures `cbb` has room for `len` additional bytes and sets
// `*out_data` to point to the beginning of that space. It returns one on
// success and zero otherwise. The caller may write up to `len` bytes to
// `*out_data` and call `CBB_did_write` to complete the write. `*out_data` is
// valid until the next operation on `cbb` or an ancestor `CBB`.
OPENSSL_EXPORT int CBB_reserve(CBB *cbb, uint8_t **out_data, size_t len);
// CBB_did_write advances |cbb| by |len| bytes, assuming the space has been
// CBB_did_write advances `cbb` by `len` bytes, assuming the space has been
// written to by the caller. It returns one on success and zero on error.
OPENSSL_EXPORT int CBB_did_write(CBB *cbb, size_t len);
// CBB_add_u8 appends an 8-bit number from |value| to |cbb|. It returns one on
// CBB_add_u8 appends an 8-bit number from `value` to `cbb`. It returns one on
// success and zero otherwise.
OPENSSL_EXPORT int CBB_add_u8(CBB *cbb, uint8_t value);
// CBB_add_u16 appends a 16-bit, big-endian number from |value| to |cbb|. It
// CBB_add_u16 appends a 16-bit, big-endian number from `value` to `cbb`. It
// returns one on success and zero otherwise.
OPENSSL_EXPORT int CBB_add_u16(CBB *cbb, uint16_t value);
// CBB_add_u16le appends a 16-bit, little-endian number from |value| to |cbb|.
// CBB_add_u16le appends a 16-bit, little-endian number from `value` to `cbb`.
// It returns one on success and zero otherwise.
OPENSSL_EXPORT int CBB_add_u16le(CBB *cbb, uint16_t value);
// CBB_add_u24 appends a 24-bit, big-endian number from |value| to |cbb|. It
// CBB_add_u24 appends a 24-bit, big-endian number from `value` to `cbb`. It
// returns one on success and zero otherwise.
OPENSSL_EXPORT int CBB_add_u24(CBB *cbb, uint32_t value);
// CBB_add_u32 appends a 32-bit, big-endian number from |value| to |cbb|. It
// CBB_add_u32 appends a 32-bit, big-endian number from `value` to `cbb`. It
// returns one on success and zero otherwise.
OPENSSL_EXPORT int CBB_add_u32(CBB *cbb, uint32_t value);
// CBB_add_u32le appends a 32-bit, little-endian number from |value| to |cbb|.
// CBB_add_u32le appends a 32-bit, little-endian number from `value` to `cbb`.
// It returns one on success and zero otherwise.
OPENSSL_EXPORT int CBB_add_u32le(CBB *cbb, uint32_t value);
// CBB_add_u64 appends a 64-bit, big-endian number from |value| to |cbb|. It
// CBB_add_u64 appends a 64-bit, big-endian number from `value` to `cbb`. It
// returns one on success and zero otherwise.
OPENSSL_EXPORT int CBB_add_u64(CBB *cbb, uint64_t value);
// CBB_add_u64le appends a 64-bit, little-endian number from |value| to |cbb|.
// CBB_add_u64le appends a 64-bit, little-endian number from `value` to `cbb`.
// It returns one on success and zero otherwise.
OPENSSL_EXPORT int CBB_add_u64le(CBB *cbb, uint64_t value);
// CBB_discard discards the last |len| bytes written to |cbb|. The process will
// abort if |cbb| has an unflushed child, or its length is smaller than |len|.
// CBB_discard discards the last `len` bytes written to `cbb`. The process will
// abort if `cbb` has an unflushed child, or its length is smaller than `len`.
OPENSSL_EXPORT void CBB_discard(CBB *cbb, size_t len);
// CBB_discard_child discards the current unflushed child of |cbb|. Neither the
// CBB_discard_child discards the current unflushed child of `cbb`. Neither the
// child's contents nor the length prefix will be included in the output.
OPENSSL_EXPORT void CBB_discard_child(CBB *cbb);
// CBB_add_asn1_element adds an ASN.1 element with the specified tag and
// contents. It returns one on success and zero on error. This is a convenience
// function over |CBB_add_asn1| when the data is already available.
// function over `CBB_add_asn1` when the data is already available.
OPENSSL_EXPORT int CBB_add_asn1_element(CBB *cbb, CBS_ASN1_TAG tag,
const uint8_t *data, size_t data_len);
// CBB_add_asn1_uint64 writes an ASN.1 INTEGER into |cbb| using |CBB_add_asn1|
// and writes |value| in its contents. It returns one on success and zero on
// CBB_add_asn1_uint64 writes an ASN.1 INTEGER into `cbb` using `CBB_add_asn1`
// and writes `value` in its contents. It returns one on success and zero on
// error.
OPENSSL_EXPORT int CBB_add_asn1_uint64(CBB *cbb, uint64_t value);
// CBB_add_asn1_uint64_with_tag behaves like |CBB_add_asn1_uint64| but uses
// |tag| as the tag instead of INTEGER. This is useful if the INTEGER type uses
// CBB_add_asn1_uint64_with_tag behaves like `CBB_add_asn1_uint64` but uses
// `tag` as the tag instead of INTEGER. This is useful if the INTEGER type uses
// implicit tagging.
OPENSSL_EXPORT int CBB_add_asn1_uint64_with_tag(CBB *cbb, uint64_t value,
CBS_ASN1_TAG tag);
// CBB_add_asn1_int64 writes an ASN.1 INTEGER into |cbb| using |CBB_add_asn1|
// and writes |value| in its contents. It returns one on success and zero on
// CBB_add_asn1_int64 writes an ASN.1 INTEGER into `cbb` using `CBB_add_asn1`
// and writes `value` in its contents. It returns one on success and zero on
// error.
OPENSSL_EXPORT int CBB_add_asn1_int64(CBB *cbb, int64_t value);
// CBB_add_asn1_int64_with_tag behaves like |CBB_add_asn1_int64| but uses |tag|
// CBB_add_asn1_int64_with_tag behaves like `CBB_add_asn1_int64` but uses `tag`
// as the tag instead of INTEGER. This is useful if the INTEGER type uses
// implicit tagging.
OPENSSL_EXPORT int CBB_add_asn1_int64_with_tag(CBB *cbb, int64_t value,
CBS_ASN1_TAG tag);
// CBB_add_asn1_octet_string writes an ASN.1 OCTET STRING into |cbb| with the
// CBB_add_asn1_octet_string writes an ASN.1 OCTET STRING into `cbb` with the
// given contents. It returns one on success and zero on error.
OPENSSL_EXPORT int CBB_add_asn1_octet_string(CBB *cbb, const uint8_t *data,
size_t data_len);
// CBB_add_asn1_bool writes an ASN.1 BOOLEAN into |cbb| which is true iff
// |value| is non-zero. It returns one on success and zero on error.
// CBB_add_asn1_bool writes an ASN.1 BOOLEAN into `cbb` which is true iff
// `value` is non-zero. It returns one on success and zero on error.
OPENSSL_EXPORT int CBB_add_asn1_bool(CBB *cbb, int value);
// CBB_add_asn1_oid_from_text decodes |len| bytes from |text| as an ASCII OID
// CBB_add_asn1_oid_from_text decodes `len` bytes from `text` as an ASCII OID
// representation, e.g. "1.2.840.113554.4.1.72585", and writes the DER-encoded
// contents to |cbb|. It returns one on success and zero on malloc failure or if
// |text| was invalid. It does not include the OBJECT IDENTIFIER framing, only
// contents to `cbb`. It returns one on success and zero on malloc failure or if
// `text` was invalid. It does not include the OBJECT IDENTIFIER framing, only
// the element's contents.
//
// This function considers OID strings with components which do not fit in a
// |uint64_t| to be invalid.
// `uint64_t` to be invalid.
OPENSSL_EXPORT int CBB_add_asn1_oid_from_text(CBB *cbb, const char *text,
size_t len);
// CBB_add_asn1_relative_oid_from_text decodes |len| bytes from |text| as an
// CBB_add_asn1_relative_oid_from_text decodes `len` bytes from `text` as an
// ASCII RELATIVE-OID representation, e.g. "32473.1", and writes the
// DER-encoded contents to |cbb|. It returns one on success and zero on malloc
// failure or if |text| was invalid. It does not include any framing, only the
// DER-encoded contents to `cbb`. It returns one on success and zero on malloc
// failure or if `text` was invalid. It does not include any framing, only the
// element's contents.
//
// This function considers OID strings with components which do not fit in a
// |uint64_t| to be invalid.
// `uint64_t` to be invalid.
OPENSSL_EXPORT int CBB_add_asn1_relative_oid_from_text(CBB *cbb,
const char *text,
size_t len);
// CBB_add_asn1_oid_component appends a single OID component to |cbb|.
// CBB_add_asn1_oid_component appends a single OID component to `cbb`.
// It returns one on success and zero on error.
OPENSSL_EXPORT int CBB_add_asn1_oid_component(CBB *cbb, uint64_t value);
// CBB_flush_asn1_set_of calls |CBB_flush| on |cbb| and then reorders the
// CBB_flush_asn1_set_of calls `CBB_flush` on `cbb` and then reorders the
// contents for a DER-encoded ASN.1 SET OF type. It returns one on success and
// zero on failure. DER canonicalizes SET OF contents by sorting
// lexicographically by encoding. Call this function when encoding a SET OF
@@ -718,21 +718,21 @@ OPENSSL_EXPORT int CBB_flush_asn1_set_of(CBB *cbb);
// These functions consider noncharacters (see section 23.7 from Unicode 15.0.0)
// to be invalid code points and will treat them as an error condition.
// The following functions read one Unicode code point from |cbs| with the
// corresponding encoding and store it in |*out|. They return one on success and
// The following functions read one Unicode code point from `cbs` with the
// corresponding encoding and store it in `*out`. They return one on success and
// zero on error.
OPENSSL_EXPORT int CBS_get_utf8(CBS *cbs, uint32_t *out);
OPENSSL_EXPORT int CBS_get_latin1(CBS *cbs, uint32_t *out);
OPENSSL_EXPORT int CBS_get_ucs2_be(CBS *cbs, uint32_t *out);
OPENSSL_EXPORT int CBS_get_utf32_be(CBS *cbs, uint32_t *out);
// CBB_get_utf8_len returns the number of bytes needed to represent |u| in
// CBB_get_utf8_len returns the number of bytes needed to represent `u` in
// UTF-8.
OPENSSL_EXPORT size_t CBB_get_utf8_len(uint32_t u);
// The following functions encode |u| to |cbb| with the corresponding
// The following functions encode `u` to `cbb` with the corresponding
// encoding. They return one on success and zero on error. Error conditions
// include |u| being an invalid code point, or |u| being unencodable in the
// include `u` being an invalid code point, or `u` being unencodable in the
// specified encoding.
OPENSSL_EXPORT int CBB_add_utf8(CBB *cbb, uint32_t u);
OPENSSL_EXPORT int CBB_add_latin1(CBB *cbb, uint32_t u);
util/update_comment_style.py
Executable
+86
View File
@@ -0,0 +1,86 @@
# Copyright 2026 The BoringSSL Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import re
import argparse
import sys
import os
def update_comment_style(cpp_code):
# Identifies C/C++ line and block comments.
comment_regex = re.compile(r'//.*|/\*[\s\S]*?\*/')
# Matches |pipes| surrounding a symbol or function call, or expression
# containing two such symbols joined by -> or + operators.
target_regex = re.compile(r'(?<!\|)\|(\*?[a-zA-Z_][a-zA-Z0-9_\.\-\*()]*((\->|\+)[a-zA-Z_][a-zA-Z0-9_\.\-\*()]*)?)\|(?!\|)')
total_replacements = 0
def process_comment(comment_match):
nonlocal total_replacements
comment_text = comment_match.group(0)
modified_comment, subs_made = target_regex.subn(r'`\1`', comment_text)
total_replacements += subs_made
return modified_comment
updated_code = comment_regex.sub(process_comment, cpp_code)
unreplaced_lines = []
for line_num, line in enumerate(updated_code.splitlines(), start=1):
if '|' in line:
unreplaced_lines.append((line_num, line))
return updated_code, total_replacements, unreplaced_lines
def main():
parser = argparse.ArgumentParser(description="Update pipe formatting to backticks within C/C++ comments.")
parser.add_argument("filepath", help="Path to the C/C++ file to modify.")
args = parser.parse_args()
file_path = args.filepath
if not os.path.isfile(file_path):
print(f"Error: '{file_path}' not found.")
sys.exit(1)
try:
with open(file_path, 'r', encoding='utf-8') as file:
code_file = file.read()
except Exception as e:
print(f"Error reading file '{file_path}': {e}")
sys.exit(1)
new_code, replace_count, leftover_pipes = update_comment_style(code_file)
try:
with open(file_path, 'w', encoding='utf-8') as file:
file.write(new_code)
except Exception as e:
print(f"Error writing to file '{file_path}': {e}")
sys.exit(1)
print("-" * 40)
print(f"--- SUMMARY FOR: {file_path} ---")
print(f"Total replacements made: {replace_count}")
if leftover_pipes:
print(f"\nFound {len(leftover_pipes)} line(s) containing unreplaced pipe '|' characters:")
for line_num, text in leftover_pipes:
print(f" Line {line_num:02d}: {text.strip()}")
else:
print("\nNo unreplaced pipe characters found in the resulting file.")
if __name__ == "__main__":
main()