Documentation: Change |...| to `...` for code references in comments 1/N 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>
diff --git a/include/openssl/aead.h b/include/openssl/aead.h index d23c16d..32c361e 100644 --- a/include/openssl/aead.h +++ b/include/openssl/aead.h
@@ -29,22 +29,22 @@ // 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 @@ // 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 @@ // 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_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 @@ // 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 @@ 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 @@ // 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 @@ 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 @@ 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 @@ 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 @@ // // 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 @@ 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 @@ 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,
diff --git a/include/openssl/aes.h b/include/openssl/aes.h index eee88a5..5dd0cfd 100644 --- a/include/openssl/aes.h +++ b/include/openssl/aes.h
@@ -41,39 +41,39 @@ }; 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 @@ 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 @@ // 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 @@ // 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);
diff --git a/include/openssl/asm_base.h b/include/openssl/asm_base.h index 926eb6f..666c5a9 100644 --- a/include/openssl/asm_base.h +++ b/include/openssl/asm_base.h
@@ -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'. //
diff --git a/include/openssl/asn1.h b/include/openssl/asn1.h index e891382..04d026b 100644 --- a/include/openssl/asn1.h +++ b/include/openssl/asn1.h
@@ -36,7 +36,7 @@ // particularly prone to behavior changes and API removals, as BoringSSL // iterates on these issues. // -// Use the new |CBS| and |CBB| library in <openssl/bytestring.h> instead. +// Use the new `CBS` and `CBB` library in <openssl/bytestring.h> instead. // Tag constants. @@ -63,7 +63,7 @@ #define V_ASN1_PRIMITIVE_TAG 0x1f // V_ASN1_MAX_UNIVERSAL is the highest supported universal tag number. It is -// necessary to avoid ambiguity with |V_ASN1_NEG| and |MBSTRING_FLAG|. +// necessary to avoid ambiguity with `V_ASN1_NEG` and `MBSTRING_FLAG`. // // TODO(davidben): Make this private. #define V_ASN1_MAX_UNIVERSAL 0xff @@ -71,7 +71,7 @@ // V_ASN1_UNDEF is used in some APIs to indicate an ASN.1 element is omitted. #define V_ASN1_UNDEF (-1) -// V_ASN1_OTHER is used in |ASN1_TYPE| to indicate a non-universal ASN.1 type. +// V_ASN1_OTHER is used in `ASN1_TYPE` to indicate a non-universal ASN.1 type. #define V_ASN1_OTHER (-3) // V_ASN1_ANY is used by the ASN.1 templates to indicate an ANY type. @@ -107,8 +107,8 @@ #define V_ASN1_UNIVERSALSTRING 28 #define V_ASN1_BMPSTRING 30 -// The following constants are used for |ASN1_STRING| values that represent -// negative INTEGER and ENUMERATED values. See |ASN1_STRING| for more details. +// The following constants are used for `ASN1_STRING` values that represent +// negative INTEGER and ENUMERATED values. See `ASN1_STRING` for more details. #define V_ASN1_NEG 0x100 #define V_ASN1_NEG_INTEGER (V_ASN1_INTEGER | V_ASN1_NEG) #define V_ASN1_NEG_ENUMERATED (V_ASN1_ENUMERATED | V_ASN1_NEG) @@ -133,12 +133,12 @@ #define B_ASN1_GENERALIZEDTIME 0x8000 #define B_ASN1_SEQUENCE 0x10000 -// ASN1_tag2bit converts |tag| from the tag number of a universal type to a -// corresponding |B_ASN1_*| constant, or zero if |tag| has no bitmask. +// ASN1_tag2bit converts `tag` from the tag number of a universal type to a +// corresponding `B_ASN1_*` constant, or zero if `tag` has no bitmask. OPENSSL_EXPORT unsigned long ASN1_tag2bit(int tag); -// ASN1_tag2str returns a string representation of |tag|, interpret as a tag -// number for a universal type, or |V_ASN1_NEG_*|. +// ASN1_tag2str returns a string representation of `tag`, interpret as a tag +// number for a universal type, or `V_ASN1_NEG_*`. OPENSSL_EXPORT const char *ASN1_tag2str(int tag); @@ -149,36 +149,36 @@ #if 0 // Sample functions -// d2i_SAMPLE parses a structure from up to |len| bytes at |*inp|. On success, -// it advances |*inp| by the number of bytes read and returns a newly-allocated -// |SAMPLE| object containing the parsed structure. If |out| is non-NULL, it -// additionally frees the previous value at |*out| and updates |*out| to the +// d2i_SAMPLE parses a structure from up to `len` bytes at `*inp`. On success, +// it advances `*inp` by the number of bytes read and returns a newly-allocated +// `SAMPLE` object containing the parsed structure. If `out` is non-NULL, it +// additionally frees the previous value at `*out` and updates `*out` to the // result. If parsing or allocating the result fails, it returns NULL. // // This function does not reject trailing data in the input. This allows the // caller to parse a sequence of concatenated structures. Callers parsing only -// one structure should check for trailing data by comparing the updated |*inp| +// one structure should check for trailing data by comparing the updated `*inp` // with the end of the input. // -// Note: If |out| and |*out| are both non-NULL, the object at |*out| is not +// Note: If `out` and `*out` are both non-NULL, the object at `*out` is not // updated in-place. Instead, it is freed, and the pointer is updated to the -// new object. This differs from OpenSSL. Callers are recommended to set |out| +// new object. This differs from OpenSSL. Callers are recommended to set `out` // to NULL and instead use the return value. SAMPLE *d2i_SAMPLE(SAMPLE **out, const uint8_t **inp, long len); -// i2d_SAMPLE marshals |in|. On error, it returns a negative value. On success, -// it returns the length of the result and outputs it via |outp| as follows: +// i2d_SAMPLE marshals `in`. On error, it returns a negative value. On success, +// it returns the length of the result and outputs it via `outp` as follows: // -// If |outp| is NULL, the function writes nothing. This mode can be used to size +// If `outp` is NULL, the function writes nothing. This mode can be used to size // buffers. // -// If |outp| is non-NULL but |*outp| is NULL, the function sets |*outp| to a +// If `outp` is non-NULL but `*outp` is NULL, the function sets `*outp` to a // newly-allocated buffer containing the result. The caller is responsible for -// releasing |*outp| with |OPENSSL_free|. This mode is recommended for most +// releasing `*outp` with `OPENSSL_free`. This mode is recommended for most // callers. // -// If |outp| and |*outp| are non-NULL, the function writes the result to -// |*outp|, which must have enough space available, and advances |*outp| just +// If `outp` and `*outp` are non-NULL, the function writes the result to +// `*outp`, which must have enough space available, and advances `*outp` just // past the output. // // WARNING: In the third mode, the function does not internally check output @@ -189,7 +189,7 @@ #endif // Sample functions // The following typedefs are sometimes used for pointers to functions like -// |d2i_SAMPLE| and |i2d_SAMPLE|. Note, however, that these act on |void*|. +// `d2i_SAMPLE` and `i2d_SAMPLE`. Note, however, that these act on `void*`. // Calling a function with a different pointer type is undefined in C, so this // is only valid with a wrapper. typedef void *d2i_of_void(void **, const unsigned char **, long); @@ -198,214 +198,214 @@ // ASN.1 types. // -// An |ASN1_ITEM| represents an ASN.1 type and allows working with ASN.1 types +// An `ASN1_ITEM` represents an ASN.1 type and allows working with ASN.1 types // generically. // -// |ASN1_ITEM|s use a different namespace from C types and are accessed via -// |ASN1_ITEM_*| macros. So, for example, |ASN1_OCTET_STRING| is both a C type -// and the name of an |ASN1_ITEM|, referenced as -// |ASN1_ITEM_rptr(ASN1_OCTET_STRING)|. +// `ASN1_ITEM`s use a different namespace from C types and are accessed via +// `ASN1_ITEM_*` macros. So, for example, `ASN1_OCTET_STRING` is both a C type +// and the name of an `ASN1_ITEM`, referenced as +// `ASN1_ITEM_rptr(ASN1_OCTET_STRING)`. // -// Each |ASN1_ITEM| has a corresponding C type, typically with the same name, +// Each `ASN1_ITEM` has a corresponding C type, typically with the same name, // which represents values in the ASN.1 type. This type is either a pointer type -// or |ASN1_BOOLEAN|. When it is a pointer, NULL pointers represent omitted +// or `ASN1_BOOLEAN`. When it is a pointer, NULL pointers represent omitted // values. For example, an OCTET STRING value is declared with the C type -// |ASN1_OCTET_STRING*| and uses the |ASN1_ITEM| named |ASN1_OCTET_STRING|. An +// `ASN1_OCTET_STRING*` and uses the `ASN1_ITEM` named `ASN1_OCTET_STRING`. An // OPTIONAL OCTET STRING uses the same C type and represents an omitted value -// with a NULL pointer. |ASN1_BOOLEAN| is described in a later section. +// with a NULL pointer. `ASN1_BOOLEAN` is described in a later section. -// DECLARE_ASN1_ITEM declares an |ASN1_ITEM| with name |name|. The |ASN1_ITEM| -// may be referenced with |ASN1_ITEM_rptr|. Uses of this macro should document +// DECLARE_ASN1_ITEM declares an `ASN1_ITEM` with name `name`. The `ASN1_ITEM` +// may be referenced with `ASN1_ITEM_rptr`. Uses of this macro should document // the corresponding ASN.1 and C types. #define DECLARE_ASN1_ITEM(name) extern OPENSSL_EXPORT const ASN1_ITEM name##_it; -// ASN1_ITEM_rptr returns the |const ASN1_ITEM *| named |name|. +// ASN1_ITEM_rptr returns the `const ASN1_ITEM *` named `name`. #define ASN1_ITEM_rptr(name) (&(name##_it)) -// ASN1_ITEM_EXP is an abstraction for referencing an |ASN1_ITEM| in a +// ASN1_ITEM_EXP is an abstraction for referencing an `ASN1_ITEM` in a // constant-initialized structure, such as a method table. It exists because, on -// some OpenSSL platforms, |ASN1_ITEM| references are indirected through -// functions. Structures reference the |ASN1_ITEM| by declaring a field like -// |ASN1_ITEM_EXP *item| and initializing it with |ASN1_ITEM_ref|. +// some OpenSSL platforms, `ASN1_ITEM` references are indirected through +// functions. Structures reference the `ASN1_ITEM` by declaring a field like +// `ASN1_ITEM_EXP *item` and initializing it with `ASN1_ITEM_ref`. typedef const ASN1_ITEM ASN1_ITEM_EXP; -// ASN1_ITEM_ref returns an |ASN1_ITEM_EXP*| for the |ASN1_ITEM| named |name|. +// ASN1_ITEM_ref returns an `ASN1_ITEM_EXP*` for the `ASN1_ITEM` named `name`. #define ASN1_ITEM_ref(name) (&(name##_it)) -// ASN1_ITEM_ptr converts |iptr|, which must be an |ASN1_ITEM_EXP*| to a -// |const ASN1_ITEM*|. +// ASN1_ITEM_ptr converts `iptr`, which must be an `ASN1_ITEM_EXP*` to a +// `const ASN1_ITEM*`. #define ASN1_ITEM_ptr(iptr) (iptr) -// ASN1_VALUE_st (aka |ASN1_VALUE|) is an opaque type used as a placeholder for -// the C type corresponding to an |ASN1_ITEM|. +// ASN1_VALUE_st (aka `ASN1_VALUE`) is an opaque type used as a placeholder for +// the C type corresponding to an `ASN1_ITEM`. typedef struct ASN1_VALUE_st ASN1_VALUE; -// ASN1_item_new allocates a new value of the C type corresponding to |it|, or +// ASN1_item_new allocates a new value of the C type corresponding to `it`, or // NULL on error. On success, the caller must release the value with -// |ASN1_item_free|, or the corresponding C type's free function, when done. The +// `ASN1_item_free`, or the corresponding C type's free function, when done. The // new value will initialize fields of the value to some default state, such as // an empty string. Note, however, that this default state sometimes omits // required values, such as with CHOICE types. // -// This function may not be used with |ASN1_ITEM|s whose C type is -// |ASN1_BOOLEAN|. +// This function may not be used with `ASN1_ITEM`s whose C type is +// `ASN1_BOOLEAN`. // // WARNING: Casting the result of this function to the wrong type is a // potentially exploitable memory error. Callers must ensure the value is used -// consistently with |it|. Prefer using type-specific functions such as -// |ASN1_OCTET_STRING_new|. +// consistently with `it`. Prefer using type-specific functions such as +// `ASN1_OCTET_STRING_new`. OPENSSL_EXPORT ASN1_VALUE *ASN1_item_new(const ASN1_ITEM *it); -// ASN1_item_free releases memory associated with |val|, which must be an object -// of the C type corresponding to |it|. +// ASN1_item_free releases memory associated with `val`, which must be an object +// of the C type corresponding to `it`. // -// This function may not be used with |ASN1_ITEM|s whose C type is -// |ASN1_BOOLEAN|. +// This function may not be used with `ASN1_ITEM`s whose C type is +// `ASN1_BOOLEAN`. // // WARNING: Passing a pointer of the wrong type into this function is a -// potentially exploitable memory error. Callers must ensure |val| is consistent -// with |it|. Prefer using type-specific functions such as -// |ASN1_OCTET_STRING_free|. +// potentially exploitable memory error. Callers must ensure `val` is consistent +// with `it`. Prefer using type-specific functions such as +// `ASN1_OCTET_STRING_free`. OPENSSL_EXPORT void ASN1_item_free(ASN1_VALUE *val, const ASN1_ITEM *it); -// ASN1_item_d2i parses the ASN.1 type |it| from up to |len| bytes at |*inp|. -// It behaves like |d2i_SAMPLE|, except that |out| and the return value are cast -// to |ASN1_VALUE| pointers. +// ASN1_item_d2i parses the ASN.1 type `it` from up to `len` bytes at `*inp`. +// It behaves like `d2i_SAMPLE`, except that `out` and the return value are cast +// to `ASN1_VALUE` pointers. // // TODO(https://crbug.com/boringssl/444): C strict aliasing forbids type-punning -// |T*| and |ASN1_VALUE*| the way this function signature does. When that bug is -// resolved, we will need to pick which type |*out| is (probably |T*|). Do not -// use a non-NULL |out| to avoid ending up on the wrong side of this question. +// `T*` and `ASN1_VALUE*` the way this function signature does. When that bug is +// resolved, we will need to pick which type `*out` is (probably `T*`). Do not +// use a non-NULL `out` to avoid ending up on the wrong side of this question. // -// This function may not be used with |ASN1_ITEM|s whose C type is -// |ASN1_BOOLEAN|. +// This function may not be used with `ASN1_ITEM`s whose C type is +// `ASN1_BOOLEAN`. // // WARNING: Casting the result of this function to the wrong type, or passing a // pointer of the wrong type into this function, are potentially exploitable -// memory errors. Callers must ensure |out| is consistent with |it|. Prefer -// using type-specific functions such as |d2i_ASN1_OCTET_STRING|. +// memory errors. Callers must ensure `out` is consistent with `it`. Prefer +// using type-specific functions such as `d2i_ASN1_OCTET_STRING`. OPENSSL_EXPORT ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **out, const unsigned char **inp, long len, const ASN1_ITEM *it); -// ASN1_item_i2d marshals |val| as the ASN.1 type associated with |it|, as -// described in |i2d_SAMPLE|. +// ASN1_item_i2d marshals `val` as the ASN.1 type associated with `it`, as +// described in `i2d_SAMPLE`. // -// This function may not be used with |ASN1_ITEM|s whose C type is -// |ASN1_BOOLEAN|. +// This function may not be used with `ASN1_ITEM`s whose C type is +// `ASN1_BOOLEAN`. // // WARNING: Passing a pointer of the wrong type into this function is a -// potentially exploitable memory error. Callers must ensure |val| is consistent -// with |it|. Prefer using type-specific functions such as -// |i2d_ASN1_OCTET_STRING|. +// potentially exploitable memory error. Callers must ensure `val` is consistent +// with `it`. Prefer using type-specific functions such as +// `i2d_ASN1_OCTET_STRING`. OPENSSL_EXPORT int ASN1_item_i2d(ASN1_VALUE *val, unsigned char **outp, const ASN1_ITEM *it); -// ASN1_item_dup returns a newly-allocated copy of |x|, or NULL on error. |x| -// must be an object of |it|'s C type. +// ASN1_item_dup returns a newly-allocated copy of `x`, or NULL on error. `x` +// must be an object of `it`'s C type. // -// This function may not be used with |ASN1_ITEM|s whose C type is -// |ASN1_BOOLEAN|. +// This function may not be used with `ASN1_ITEM`s whose C type is +// `ASN1_BOOLEAN`. // // WARNING: Casting the result of this function to the wrong type, or passing a // pointer of the wrong type into this function, are potentially exploitable // memory errors. Prefer using type-specific functions such as -// |ASN1_STRING_dup|. +// `ASN1_STRING_dup`. OPENSSL_EXPORT void *ASN1_item_dup(const ASN1_ITEM *it, void *x); -// The following functions behave like |ASN1_item_d2i| but read from |in| -// instead. |out| is the same parameter as in |ASN1_item_d2i|, but written with -// |void*| instead. The return values similarly match. +// The following functions behave like `ASN1_item_d2i` but read from `in` +// instead. `out` is the same parameter as in `ASN1_item_d2i`, but written with +// `void*` instead. The return values similarly match. // -// These functions may not be used with |ASN1_ITEM|s whose C type is -// |ASN1_BOOLEAN|. +// These functions may not be used with `ASN1_ITEM`s whose C type is +// `ASN1_BOOLEAN`. // -// WARNING: These functions do not bound how much data is read from |in|. +// WARNING: These functions do not bound how much data is read from `in`. // Parsing an untrusted input could consume unbounded memory. OPENSSL_EXPORT void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *out); OPENSSL_EXPORT void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *out); -// The following functions behave like |ASN1_item_i2d| but write to |out| -// instead. |in| is the same parameter as in |ASN1_item_i2d|, but written with -// |void*| instead. +// The following functions behave like `ASN1_item_i2d` but write to `out` +// instead. `in` is the same parameter as in `ASN1_item_i2d`, but written with +// `void*` instead. // -// These functions may not be used with |ASN1_ITEM|s whose C type is -// |ASN1_BOOLEAN|. +// These functions may not be used with `ASN1_ITEM`s whose C type is +// `ASN1_BOOLEAN`. OPENSSL_EXPORT int ASN1_item_i2d_fp(const ASN1_ITEM *it, FILE *out, const void *in); OPENSSL_EXPORT int ASN1_item_i2d_bio(const ASN1_ITEM *it, BIO *out, const void *in); -// ASN1_item_unpack parses |oct|'s contents as |it|'s ASN.1 type. It returns a -// newly-allocated instance of |it|'s C type on success, or NULL on error. +// ASN1_item_unpack parses `oct`'s contents as `it`'s ASN.1 type. It returns a +// newly-allocated instance of `it`'s C type on success, or NULL on error. // -// This function may not be used with |ASN1_ITEM|s whose C type is -// |ASN1_BOOLEAN|. +// This function may not be used with `ASN1_ITEM`s whose C type is +// `ASN1_BOOLEAN`. // // WARNING: Casting the result of this function to the wrong type is a // potentially exploitable memory error. Callers must ensure the value is used -// consistently with |it|. +// consistently with `it`. OPENSSL_EXPORT void *ASN1_item_unpack(const ASN1_STRING *oct, const ASN1_ITEM *it); -// ASN1_item_pack marshals |obj| as |it|'s ASN.1 type. If |out| is NULL, it -// returns a newly-allocated |ASN1_STRING| with the result, or NULL on error. -// If |out| is non-NULL, but |*out| is NULL, it does the same but additionally -// sets |*out| to the result. If both |out| and |*out| are non-NULL, it writes -// the result to |*out| and returns |*out| on success or NULL on error. +// ASN1_item_pack marshals `obj` as `it`'s ASN.1 type. If `out` is NULL, it +// returns a newly-allocated `ASN1_STRING` with the result, or NULL on error. +// If `out` is non-NULL, but `*out` is NULL, it does the same but additionally +// sets `*out` to the result. If both `out` and `*out` are non-NULL, it writes +// the result to `*out` and returns `*out` on success or NULL on error. // -// This function may not be used with |ASN1_ITEM|s whose C type is -// |ASN1_BOOLEAN|. +// This function may not be used with `ASN1_ITEM`s whose C type is +// `ASN1_BOOLEAN`. // // WARNING: Passing a pointer of the wrong type into this function is a -// potentially exploitable memory error. Callers must ensure |val| is consistent -// with |it|. +// potentially exploitable memory error. Callers must ensure `val` is consistent +// with `it`. OPENSSL_EXPORT ASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it, ASN1_STRING **out); // Booleans. // -// This library represents ASN.1 BOOLEAN values with |ASN1_BOOLEAN|, which is an +// This library represents ASN.1 BOOLEAN values with `ASN1_BOOLEAN`, which is an // integer type. FALSE is zero, TRUE is 0xff, and an omitted OPTIONAL BOOLEAN is // -1. -// ASN1_BOOLEAN_FALSE is FALSE as an |ASN1_BOOLEAN|. +// ASN1_BOOLEAN_FALSE is FALSE as an `ASN1_BOOLEAN`. #define ASN1_BOOLEAN_FALSE 0 -// ASN1_BOOLEAN_TRUE is TRUE as an |ASN1_BOOLEAN|. Some code incorrectly uses -// 1, so prefer |b != ASN1_BOOLEAN_FALSE| over |b == ASN1_BOOLEAN_TRUE|. +// ASN1_BOOLEAN_TRUE is TRUE as an `ASN1_BOOLEAN`. Some code incorrectly uses +// 1, so prefer `b != ASN1_BOOLEAN_FALSE` over `b == ASN1_BOOLEAN_TRUE`. #define ASN1_BOOLEAN_TRUE 0xff -// ASN1_BOOLEAN_NONE, in contexts where the |ASN1_BOOLEAN| represents an +// ASN1_BOOLEAN_NONE, in contexts where the `ASN1_BOOLEAN` represents an // OPTIONAL BOOLEAN, is an omitted value. Using this value in other contexts is // undefined and may be misinterpreted as TRUE. #define ASN1_BOOLEAN_NONE (-1) -// d2i_ASN1_BOOLEAN parses a DER-encoded ASN.1 BOOLEAN from up to |len| bytes at -// |*inp|. On success, it advances |*inp| by the number of bytes read and -// returns the result. If |out| is non-NULL, it additionally writes the result -// to |*out|. On error, it returns |ASN1_BOOLEAN_NONE|. +// d2i_ASN1_BOOLEAN parses a DER-encoded ASN.1 BOOLEAN from up to `len` bytes at +// `*inp`. On success, it advances `*inp` by the number of bytes read and +// returns the result. If `out` is non-NULL, it additionally writes the result +// to `*out`. On error, it returns `ASN1_BOOLEAN_NONE`. // // This function does not reject trailing data in the input. This allows the // caller to parse a sequence of concatenated structures. Callers parsing only -// one structure should check for trailing data by comparing the updated |*inp| +// one structure should check for trailing data by comparing the updated `*inp` // with the end of the input. // -// WARNING: This function's is slightly different from other |d2i_*| functions -// because |ASN1_BOOLEAN| is not a pointer type. +// WARNING: This function's is slightly different from other `d2i_*` functions +// because `ASN1_BOOLEAN` is not a pointer type. OPENSSL_EXPORT ASN1_BOOLEAN d2i_ASN1_BOOLEAN(ASN1_BOOLEAN *out, const unsigned char **inp, long len); -// i2d_ASN1_BOOLEAN marshals |a| as a DER-encoded ASN.1 BOOLEAN, as described in -// |i2d_SAMPLE|. +// i2d_ASN1_BOOLEAN marshals `a` as a DER-encoded ASN.1 BOOLEAN, as described in +// `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_BOOLEAN(ASN1_BOOLEAN a, unsigned char **outp); -// The following |ASN1_ITEM|s have ASN.1 type BOOLEAN and C type |ASN1_BOOLEAN|. -// |ASN1_TBOOLEAN| and |ASN1_FBOOLEAN| must be marked OPTIONAL. When omitted, +// The following `ASN1_ITEM`s have ASN.1 type BOOLEAN and C type `ASN1_BOOLEAN`. +// `ASN1_TBOOLEAN` and `ASN1_FBOOLEAN` must be marked OPTIONAL. When omitted, // they are parsed as TRUE and FALSE, respectively, rather than -// |ASN1_BOOLEAN_NONE|. +// `ASN1_BOOLEAN_NONE`. DECLARE_ASN1_ITEM(ASN1_BOOLEAN) DECLARE_ASN1_ITEM(ASN1_TBOOLEAN) DECLARE_ASN1_ITEM(ASN1_FBOOLEAN) @@ -415,71 +415,71 @@ // // ASN.1 contains a myriad of string types, as well as types that contain data // that may be encoded into a string. This library uses a single type, -// |ASN1_STRING|, to represent most values. +// `ASN1_STRING`, to represent most values. -// An asn1_string_st (aka |ASN1_STRING|) represents a value of a string-like -// ASN.1 type. It contains a |type| field, and a byte string |data| field with a +// An asn1_string_st (aka `ASN1_STRING`) represents a value of a string-like +// ASN.1 type. It contains a `type` field, and a byte string `data` field with a // type-specific representation. This type-specific representation does not // always correspond to the DER encoding of the type. // -// If |type| is one of |V_ASN1_OCTET_STRING|, |V_ASN1_UTF8STRING|, -// |V_ASN1_NUMERICSTRING|, |V_ASN1_PRINTABLESTRING|, |V_ASN1_T61STRING|, -// |V_ASN1_VIDEOTEXSTRING|, |V_ASN1_IA5STRING|, |V_ASN1_GRAPHICSTRING|, -// |V_ASN1_ISO64STRING|, |V_ASN1_VISIBLESTRING|, |V_ASN1_GENERALSTRING|, -// |V_ASN1_UNIVERSALSTRING|, or |V_ASN1_BMPSTRING|, the object represents an +// If `type` is one of `V_ASN1_OCTET_STRING`, `V_ASN1_UTF8STRING`, +// `V_ASN1_NUMERICSTRING`, `V_ASN1_PRINTABLESTRING`, `V_ASN1_T61STRING`, +// `V_ASN1_VIDEOTEXSTRING`, `V_ASN1_IA5STRING`, `V_ASN1_GRAPHICSTRING`, +// `V_ASN1_ISO64STRING`, `V_ASN1_VISIBLESTRING`, `V_ASN1_GENERALSTRING`, +// `V_ASN1_UNIVERSALSTRING`, or `V_ASN1_BMPSTRING`, the object represents an // ASN.1 string type. The data contains the byte representation of the // string. // -// If |type| is |V_ASN1_BIT_STRING|, the object represents a BIT STRING value. +// If `type` is `V_ASN1_BIT_STRING`, the object represents a BIT STRING value. // See bit string documentation below for the data and flags. // -// If |type| is one of |V_ASN1_INTEGER|, |V_ASN1_NEG_INTEGER|, -// |V_ASN1_ENUMERATED|, or |V_ASN1_NEG_ENUMERATED|, the object represents an +// If `type` is one of `V_ASN1_INTEGER`, `V_ASN1_NEG_INTEGER`, +// `V_ASN1_ENUMERATED`, or `V_ASN1_NEG_ENUMERATED`, the object represents an // INTEGER or ENUMERATED value. See integer documentation below for details. // -// If |type| is |V_ASN1_GENERALIZEDTIME| or |V_ASN1_UTCTIME|, the object +// If `type` is `V_ASN1_GENERALIZEDTIME` or `V_ASN1_UTCTIME`, the object // represents a GeneralizedTime or UTCTime value, respectively. The data // contains the DER encoding of the value. For example, the UNIX epoch would be // "19700101000000Z" for a GeneralizedTime and "700101000000Z" for a UTCTime. // -// If |type| is |V_ASN1_SEQUENCE|, |V_ASN1_SET|, or |V_ASN1_OTHER|, the object +// If `type` is `V_ASN1_SEQUENCE`, `V_ASN1_SET`, or `V_ASN1_OTHER`, the object // represents a SEQUENCE, SET, or arbitrary ASN.1 value, respectively. Unlike // the above cases, the data contains the DER encoding of the entire structure, // including the header. If the value is explicitly or implicitly tagged, this // too will be reflected in the data field. As this case handles unknown types, // the contents are not checked when parsing or serializing. // -// Other values of |type| do not represent a valid ASN.1 value, though -// default-constructed objects may set |type| to -1. Such objects cannot be +// Other values of `type` do not represent a valid ASN.1 value, though +// default-constructed objects may set `type` to -1. Such objects cannot be // serialized. // -// |ASN1_STRING| additionally has the following typedefs: |ASN1_BIT_STRING|, -// |ASN1_BMPSTRING|, |ASN1_ENUMERATED|, |ASN1_GENERALIZEDTIME|, -// |ASN1_GENERALSTRING|, |ASN1_IA5STRING|, |ASN1_INTEGER|, |ASN1_OCTET_STRING|, -// |ASN1_PRINTABLESTRING|, |ASN1_T61STRING|, |ASN1_TIME|, -// |ASN1_UNIVERSALSTRING|, |ASN1_UTCTIME|, |ASN1_UTF8STRING|, and -// |ASN1_VISIBLESTRING|. Other than |ASN1_TIME|, these correspond to universal -// ASN.1 types. |ASN1_TIME| represents a CHOICE of UTCTime and GeneralizedTime, +// `ASN1_STRING` additionally has the following typedefs: `ASN1_BIT_STRING`, +// `ASN1_BMPSTRING`, `ASN1_ENUMERATED`, `ASN1_GENERALIZEDTIME`, +// `ASN1_GENERALSTRING`, `ASN1_IA5STRING`, `ASN1_INTEGER`, `ASN1_OCTET_STRING`, +// `ASN1_PRINTABLESTRING`, `ASN1_T61STRING`, `ASN1_TIME`, +// `ASN1_UNIVERSALSTRING`, `ASN1_UTCTIME`, `ASN1_UTF8STRING`, and +// `ASN1_VISIBLESTRING`. Other than `ASN1_TIME`, these correspond to universal +// ASN.1 types. `ASN1_TIME` represents a CHOICE of UTCTime and GeneralizedTime, // with a cutoff of 2049, as used in Section 4.1.2.5 of RFC 5280. // // For clarity, callers are encouraged to use the appropriate typedef when -// available. They are the same type as |ASN1_STRING|, so a caller may freely -// pass them into functions expecting |ASN1_STRING|, such as -// |ASN1_STRING_length|. +// available. They are the same type as `ASN1_STRING`, so a caller may freely +// pass them into functions expecting `ASN1_STRING`, such as +// `ASN1_STRING_length`. // -// If a function returns an |ASN1_STRING| where the typedef or ASN.1 structure -// implies constraints on |type|, callers may assume that |type| is correct. -// However, if a function takes an |ASN1_STRING| as input, callers must ensure -// |type| matches. These invariants are not captured by the C type system and +// If a function returns an `ASN1_STRING` where the typedef or ASN.1 structure +// implies constraints on `type`, callers may assume that `type` is correct. +// However, if a function takes an `ASN1_STRING` as input, callers must ensure +// `type` matches. These invariants are not captured by the C type system and // may not be checked at runtime. For example, callers may assume the output of -// |X509_get0_serialNumber| has type |V_ASN1_INTEGER| or |V_ASN1_NEG_INTEGER|. -// Callers must not pass a string of type |V_ASN1_OCTET_STRING| to -// |X509_set_serialNumber|. Doing so may break invariants on the |X509| object -// and break the |X509_get0_serialNumber| invariant. +// `X509_get0_serialNumber` has type `V_ASN1_INTEGER` or `V_ASN1_NEG_INTEGER`. +// Callers must not pass a string of type `V_ASN1_OCTET_STRING` to +// `X509_set_serialNumber`. Doing so may break invariants on the `X509` object +// and break the `X509_get0_serialNumber` invariant. // // TODO(https://crbug.com/boringssl/445): This is very unfriendly. Getting the // type field wrong should not cause memory errors, but it may do strange -// things. We should add runtime checks to anything that consumes |ASN1_STRING|s +// things. We should add runtime checks to anything that consumes `ASN1_STRING`s // from the caller. struct asn1_string_st { int length; @@ -488,91 +488,91 @@ long flags; }; -// ASN1_STRING_type_new returns a newly-allocated empty |ASN1_STRING| object of -// type |type|, or NULL on error. +// ASN1_STRING_type_new returns a newly-allocated empty `ASN1_STRING` object of +// type `type`, or NULL on error. OPENSSL_EXPORT ASN1_STRING *ASN1_STRING_type_new(int type); -// ASN1_STRING_new returns a newly-allocated empty |ASN1_STRING| object with an +// ASN1_STRING_new returns a newly-allocated empty `ASN1_STRING` object with an // arbitrary type. Prefer one of the type-specific constructors, such as -// |ASN1_OCTET_STRING_new|, or |ASN1_STRING_type_new|. +// `ASN1_OCTET_STRING_new`, or `ASN1_STRING_type_new`. OPENSSL_EXPORT ASN1_STRING *ASN1_STRING_new(void); -// ASN1_STRING_free releases memory associated with |str|. +// ASN1_STRING_free releases memory associated with `str`. OPENSSL_EXPORT void ASN1_STRING_free(ASN1_STRING *str); -// ASN1_STRING_copy sets |dst| to a copy of |str|. It returns one on success and +// ASN1_STRING_copy sets `dst` to a copy of `str`. It returns one on success and // zero on error. OPENSSL_EXPORT int ASN1_STRING_copy(ASN1_STRING *dst, const ASN1_STRING *str); -// ASN1_STRING_dup returns a newly-allocated copy of |str|, or NULL on error. +// ASN1_STRING_dup returns a newly-allocated copy of `str`, or NULL on error. OPENSSL_EXPORT ASN1_STRING *ASN1_STRING_dup(const ASN1_STRING *str); -// ASN1_STRING_type returns the type of |str|. This value will be one of the -// |V_ASN1_*| constants. +// ASN1_STRING_type returns the type of `str`. This value will be one of the +// `V_ASN1_*` constants. OPENSSL_EXPORT int ASN1_STRING_type(const ASN1_STRING *str); -// ASN1_STRING_get0_data returns a pointer to |str|'s contents. Callers should -// use |ASN1_STRING_length| to determine the length of the string. The string +// ASN1_STRING_get0_data returns a pointer to `str`'s contents. Callers should +// use `ASN1_STRING_length` to determine the length of the string. The string // may have embedded NUL bytes and may not be NUL-terminated. // -// The contents of an |ASN1_STRING| encode the value in some type-specific +// The contents of an `ASN1_STRING` encode the value in some type-specific // representation that does not always correspond to the DER encoding of the -// type. See the documentation for |ASN1_STRING| for details. +// type. See the documentation for `ASN1_STRING` for details. OPENSSL_EXPORT const unsigned char *ASN1_STRING_get0_data( const ASN1_STRING *str); -// ASN1_STRING_data returns a mutable pointer to |str|'s contents. Callers -// should use |ASN1_STRING_length| to determine the length of the string. The +// ASN1_STRING_data returns a mutable pointer to `str`'s contents. Callers +// should use `ASN1_STRING_length` to determine the length of the string. The // string may have embedded NUL bytes and may not be NUL-terminated. // -// The contents of an |ASN1_STRING| encode the value in some type-specific +// The contents of an `ASN1_STRING` encode the value in some type-specific // representation that does not always correspond to the DER encoding of the -// type. See the documentation for |ASN1_STRING| for details. +// type. See the documentation for `ASN1_STRING` for details. // -// Prefer |ASN1_STRING_get0_data|. +// Prefer `ASN1_STRING_get0_data`. OPENSSL_EXPORT unsigned char *ASN1_STRING_data(ASN1_STRING *str); -// ASN1_STRING_length returns the length of |str|, in bytes. +// ASN1_STRING_length returns the length of `str`, in bytes. // -// The contents of an |ASN1_STRING| encode the value in some type-specific +// The contents of an `ASN1_STRING` encode the value in some type-specific // representation that does not always correspond to the DER encoding of the -// type. See the documentation for |ASN1_STRING| for details. +// type. See the documentation for `ASN1_STRING` for details. OPENSSL_EXPORT int ASN1_STRING_length(const ASN1_STRING *str); -// ASN1_STRING_cmp compares |a| and |b|'s type and contents. It returns an -// integer equal to, less than, or greater than zero if |a| is equal to, less -// than, or greater than |b|, respectively. This function compares by length, -// then data, then type. Note the data compared is the |ASN1_STRING| internal +// ASN1_STRING_cmp compares `a` and `b`'s type and contents. It returns an +// integer equal to, less than, or greater than zero if `a` is equal to, less +// than, or greater than `b`, respectively. This function compares by length, +// then data, then type. Note the data compared is the `ASN1_STRING` internal // representation and the type order is arbitrary. While this comparison is -// suitable for sorting, callers should not rely on the exact order when |a| -// and |b| are different types. +// suitable for sorting, callers should not rely on the exact order when `a` +// and `b` are different types. // -// Note that, if |a| and |b| are INTEGERs, this comparison does not order the -// values numerically. For a numerical comparison, use |ASN1_INTEGER_cmp|. +// Note that, if `a` and `b` are INTEGERs, this comparison does not order the +// values numerically. For a numerical comparison, use `ASN1_INTEGER_cmp`. OPENSSL_EXPORT int ASN1_STRING_cmp(const ASN1_STRING *a, const ASN1_STRING *b); -// ASN1_STRING_set sets the contents of |str| to a copy of |len| bytes from -// |data|. It returns one on success and zero on error. If |data| is NULL, it +// ASN1_STRING_set sets the contents of `str` to a copy of `len` bytes from +// `data`. It returns one on success and zero on error. If `data` is NULL, it // updates the length and allocates the buffer as needed, but does not // initialize the contents. // -// If |str| is a BIT STRING, this function sets the number of unused bits to -// zero. |ASN1_BIT_STRING_set1| may be used to set a BIT STRING that is not a +// If `str` is a BIT STRING, this function sets the number of unused bits to +// zero. `ASN1_BIT_STRING_set1` may be used to set a BIT STRING that is not a // whole number of bytes. OPENSSL_EXPORT int ASN1_STRING_set(ASN1_STRING *str, const void *data, ossl_ssize_t len); -// ASN1_STRING_set0 sets the contents of |str| to |len| bytes from |data|. It -// takes ownership of |data|, which must have been allocated with -// |OPENSSL_malloc|. +// ASN1_STRING_set0 sets the contents of `str` to `len` bytes from `data`. It +// takes ownership of `data`, which must have been allocated with +// `OPENSSL_malloc`. // -// If |str| is a BIT STRING, this function sets the number of unused bits to -// zero. |ASN1_BIT_STRING_set1| may be used to set a BIT STRING that is not a +// If `str` is a BIT STRING, this function sets the number of unused bits to +// zero. `ASN1_BIT_STRING_set1` may be used to set a BIT STRING that is not a // whole number of bytes. OPENSSL_EXPORT void ASN1_STRING_set0(ASN1_STRING *str, void *data, int len); -// The following functions call |ASN1_STRING_type_new| with the corresponding -// |V_ASN1_*| constant. +// The following functions call `ASN1_STRING_type_new` with the corresponding +// `V_ASN1_*` constant. OPENSSL_EXPORT ASN1_BMPSTRING *ASN1_BMPSTRING_new(void); OPENSSL_EXPORT ASN1_GENERALSTRING *ASN1_GENERALSTRING_new(void); OPENSSL_EXPORT ASN1_IA5STRING *ASN1_IA5STRING_new(void); @@ -583,7 +583,7 @@ OPENSSL_EXPORT ASN1_UTF8STRING *ASN1_UTF8STRING_new(void); OPENSSL_EXPORT ASN1_VISIBLESTRING *ASN1_VISIBLESTRING_new(void); -// The following functions call |ASN1_STRING_free|. +// The following functions call `ASN1_STRING_free`. OPENSSL_EXPORT void ASN1_BMPSTRING_free(ASN1_BMPSTRING *str); OPENSSL_EXPORT void ASN1_GENERALSTRING_free(ASN1_GENERALSTRING *str); OPENSSL_EXPORT void ASN1_IA5STRING_free(ASN1_IA5STRING *str); @@ -594,9 +594,9 @@ OPENSSL_EXPORT void ASN1_UTF8STRING_free(ASN1_UTF8STRING *str); OPENSSL_EXPORT void ASN1_VISIBLESTRING_free(ASN1_VISIBLESTRING *str); -// The following functions parse up to |len| bytes from |*inp| as a +// The following functions parse up to `len` bytes from `*inp` as a // DER-encoded ASN.1 value of the corresponding type, as described in -// |d2i_SAMPLE|. +// `d2i_SAMPLE`. OPENSSL_EXPORT ASN1_BMPSTRING *d2i_ASN1_BMPSTRING(ASN1_BMPSTRING **out, const uint8_t **inp, long len); @@ -621,8 +621,8 @@ OPENSSL_EXPORT ASN1_VISIBLESTRING *d2i_ASN1_VISIBLESTRING( ASN1_VISIBLESTRING **out, const uint8_t **inp, long len); -// The following functions marshal |in| as a DER-encoded ASN.1 value of the -// corresponding type, as described in |i2d_SAMPLE|. +// The following functions marshal `in` as a DER-encoded ASN.1 value of the +// corresponding type, as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_BMPSTRING(const ASN1_BMPSTRING *in, uint8_t **outp); OPENSSL_EXPORT int i2d_ASN1_GENERALSTRING(const ASN1_GENERALSTRING *in, uint8_t **outp); @@ -639,8 +639,8 @@ OPENSSL_EXPORT int i2d_ASN1_VISIBLESTRING(const ASN1_VISIBLESTRING *in, uint8_t **outp); -// The following |ASN1_ITEM|s have the ASN.1 type referred to in their name and -// C type |ASN1_STRING*|. The C type may also be written as the corresponding +// The following `ASN1_ITEM`s have the ASN.1 type referred to in their name and +// C type `ASN1_STRING*`. The C type may also be written as the corresponding // typedef. DECLARE_ASN1_ITEM(ASN1_BMPSTRING) DECLARE_ASN1_ITEM(ASN1_GENERALSTRING) @@ -652,27 +652,27 @@ DECLARE_ASN1_ITEM(ASN1_UTF8STRING) DECLARE_ASN1_ITEM(ASN1_VISIBLESTRING) -// ASN1_OCTET_STRING_dup calls |ASN1_STRING_dup|. +// ASN1_OCTET_STRING_dup calls `ASN1_STRING_dup`. OPENSSL_EXPORT ASN1_OCTET_STRING *ASN1_OCTET_STRING_dup( const ASN1_OCTET_STRING *a); -// ASN1_OCTET_STRING_cmp calls |ASN1_STRING_cmp|. +// ASN1_OCTET_STRING_cmp calls `ASN1_STRING_cmp`. OPENSSL_EXPORT int ASN1_OCTET_STRING_cmp(const ASN1_OCTET_STRING *a, const ASN1_OCTET_STRING *b); -// ASN1_OCTET_STRING_set calls |ASN1_STRING_set|. +// ASN1_OCTET_STRING_set calls `ASN1_STRING_set`. OPENSSL_EXPORT int ASN1_OCTET_STRING_set(ASN1_OCTET_STRING *str, const unsigned char *data, int len); -// ASN1_STRING_to_UTF8 converts |in| to UTF-8. On success, sets |*out| to a +// ASN1_STRING_to_UTF8 converts `in` to UTF-8. On success, sets `*out` to a // newly-allocated buffer containing the resulting string and returns the length -// of the string. The caller must call |OPENSSL_free| to release |*out| when +// of the string. The caller must call `OPENSSL_free` to release `*out` when // done. On error, it returns a negative number. OPENSSL_EXPORT int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in); // The following formats define encodings for use with functions like -// |ASN1_mbstring_copy|. Note |MBSTRING_ASC| refers to Latin-1, not ASCII. +// `ASN1_mbstring_copy`. Note `MBSTRING_ASC` refers to Latin-1, not ASCII. #define MBSTRING_FLAG 0x1000 #define MBSTRING_UTF8 (MBSTRING_FLAG) #define MBSTRING_ASC (MBSTRING_FLAG | 1) @@ -687,80 +687,80 @@ // PKCS9STRING_TYPE contains the valid string types in a PKCS9String. #define PKCS9STRING_TYPE (DIRSTRING_TYPE | B_ASN1_IA5STRING) -// ASN1_mbstring_copy converts |len| bytes from |in| to an ASN.1 string. If -// |len| is -1, |in| must be NUL-terminated and the length is determined by -// |strlen|. |in| is decoded according to |inform|, which must be one of -// |MBSTRING_*|. |mask| determines the set of valid output types and is a -// bitmask containing a subset of |B_ASN1_PRINTABLESTRING|, |B_ASN1_IA5STRING|, -// |B_ASN1_T61STRING|, |B_ASN1_BMPSTRING|, |B_ASN1_UNIVERSALSTRING|, and -// |B_ASN1_UTF8STRING|, in that preference order. This function chooses the -// first output type in |mask| which can represent |in|. It interprets T61String +// ASN1_mbstring_copy converts `len` bytes from `in` to an ASN.1 string. If +// `len` is -1, `in` must be NUL-terminated and the length is determined by +// `strlen`. `in` is decoded according to `inform`, which must be one of +// `MBSTRING_*`. `mask` determines the set of valid output types and is a +// bitmask containing a subset of `B_ASN1_PRINTABLESTRING`, `B_ASN1_IA5STRING`, +// `B_ASN1_T61STRING`, `B_ASN1_BMPSTRING`, `B_ASN1_UNIVERSALSTRING`, and +// `B_ASN1_UTF8STRING`, in that preference order. This function chooses the +// first output type in `mask` which can represent `in`. It interprets T61String // as Latin-1, rather than T.61. // -// If |mask| is zero, |DIRSTRING_TYPE| is used by default. +// If `mask` is zero, `DIRSTRING_TYPE` is used by default. // -// On success, this function returns the |V_ASN1_*| constant corresponding to -// the selected output type and, if |out| and |*out| are both non-NULL, updates -// the object at |*out| with the result. If |out| is non-NULL and |*out| is -// NULL, it instead sets |*out| to a newly-allocated |ASN1_STRING| containing -// the result. If |out| is NULL, it returns the selected output type without -// constructing an |ASN1_STRING|. On error, this function returns -1. +// On success, this function returns the `V_ASN1_*` constant corresponding to +// the selected output type and, if `out` and `*out` are both non-NULL, updates +// the object at `*out` with the result. If `out` is non-NULL and `*out` is +// NULL, it instead sets `*out` to a newly-allocated `ASN1_STRING` containing +// the result. If `out` is NULL, it returns the selected output type without +// constructing an `ASN1_STRING`. On error, this function returns -1. OPENSSL_EXPORT int ASN1_mbstring_copy(ASN1_STRING **out, const uint8_t *in, ossl_ssize_t len, int inform, unsigned long mask); -// ASN1_mbstring_ncopy behaves like |ASN1_mbstring_copy| but returns an error if -// the input is less than |minsize| or greater than |maxsize| codepoints long. A -// |maxsize| value of zero is ignored. Note the sizes are measured in +// ASN1_mbstring_ncopy behaves like `ASN1_mbstring_copy` but returns an error if +// the input is less than `minsize` or greater than `maxsize` codepoints long. A +// `maxsize` value of zero is ignored. Note the sizes are measured in // codepoints, not output bytes. OPENSSL_EXPORT int ASN1_mbstring_ncopy(ASN1_STRING **out, const uint8_t *in, ossl_ssize_t len, int inform, unsigned long mask, ossl_ssize_t minsize, ossl_ssize_t maxsize); -// ASN1_STRING_set_by_NID behaves like |ASN1_mbstring_ncopy|, but determines -// |mask|, |minsize|, and |maxsize| based on |nid|. When |nid| is a recognized +// ASN1_STRING_set_by_NID behaves like `ASN1_mbstring_ncopy`, but determines +// `mask`, `minsize`, and `maxsize` based on `nid`. When `nid` is a recognized // X.509 attribute type, it will pick a suitable ASN.1 string type and bounds. -// For most attribute types, it preferentially chooses UTF8String. If |nid| is +// For most attribute types, it preferentially chooses UTF8String. If `nid` is // unrecognized, it uses UTF8String by default. This function will also enforce // any known attribute-specific constraints on the sizes of the string and fail // if the size is invalid. In RFC 5280, these bounds are specified by // constraints like "SIZE (1..ub-common-name)" in ASN.1. // -// Slightly unlike |ASN1_mbstring_ncopy|, this function interprets |out| and -// returns its result as follows: If |out| is NULL, it returns a newly-allocated -// |ASN1_STRING| containing the result. If |out| is non-NULL and -// |*out| is NULL, it additionally sets |*out| to the result. If both |out| and -// |*out| are non-NULL, it instead updates the object at |*out| and returns -// |*out|. In all cases, it returns NULL on error. +// Slightly unlike `ASN1_mbstring_ncopy`, this function interprets `out` and +// returns its result as follows: If `out` is NULL, it returns a newly-allocated +// `ASN1_STRING` containing the result. If `out` is non-NULL and +// `*out` is NULL, it additionally sets `*out` to the result. If both `out` and +// `*out` are non-NULL, it instead updates the object at `*out` and returns +// `*out`. In all cases, it returns NULL on error. // -// This function supports the following NIDs: |NID_countryName|, -// |NID_dnQualifier|, |NID_domainComponent|, |NID_friendlyName|, -// |NID_givenName|, |NID_initials|, |NID_localityName|, |NID_ms_csp_name|, -// |NID_name|, |NID_organizationalUnitName|, |NID_organizationName|, -// |NID_pkcs9_challengePassword|, |NID_pkcs9_emailAddress|, -// |NID_pkcs9_unstructuredAddress|, |NID_pkcs9_unstructuredName|, -// |NID_serialNumber|, |NID_stateOrProvinceName|, and |NID_surname|. Additional -// NIDs may be registered with |ASN1_STRING_set_by_NID|, but it is recommended -// to call |ASN1_mbstring_ncopy| directly instead. +// This function supports the following NIDs: `NID_countryName`, +// `NID_dnQualifier`, `NID_domainComponent`, `NID_friendlyName`, +// `NID_givenName`, `NID_initials`, `NID_localityName`, `NID_ms_csp_name`, +// `NID_name`, `NID_organizationalUnitName`, `NID_organizationName`, +// `NID_pkcs9_challengePassword`, `NID_pkcs9_emailAddress`, +// `NID_pkcs9_unstructuredAddress`, `NID_pkcs9_unstructuredName`, +// `NID_serialNumber`, `NID_stateOrProvinceName`, and `NID_surname`. Additional +// NIDs may be registered with `ASN1_STRING_set_by_NID`, but it is recommended +// to call `ASN1_mbstring_ncopy` directly instead. OPENSSL_EXPORT ASN1_STRING *ASN1_STRING_set_by_NID(ASN1_STRING **out, const unsigned char *in, ossl_ssize_t len, int inform, int nid); -// STABLE_NO_MASK causes |ASN1_STRING_TABLE_add| to allow types other than +// STABLE_NO_MASK causes `ASN1_STRING_TABLE_add` to allow types other than // UTF8String. #define STABLE_NO_MASK 0x02 -// ASN1_STRING_TABLE_add registers the corresponding parameters with |nid|, for -// use with |ASN1_STRING_set_by_NID|. It returns one on success and zero on -// error. It is an error to call this function if |nid| is a built-in NID, or +// ASN1_STRING_TABLE_add registers the corresponding parameters with `nid`, for +// use with `ASN1_STRING_set_by_NID`. It returns one on success and zero on +// error. It is an error to call this function if `nid` is a built-in NID, or // was already registered by a previous call. // // WARNING: This function affects global state in the library. If two libraries // in the same address space register information for the same OID, one call // will fail. Prefer directly passing the desired parameters to -// |ASN1_mbstring_copy| or |ASN1_mbstring_ncopy| instead. +// `ASN1_mbstring_copy` or `ASN1_mbstring_ncopy` instead. OPENSSL_EXPORT int ASN1_STRING_TABLE_add(int nid, long minsize, long maxsize, unsigned long mask, unsigned long flags); @@ -768,11 +768,11 @@ // Multi-strings. // -// A multi-string, or "MSTRING", is an |ASN1_STRING| that represents a CHOICE of +// A multi-string, or "MSTRING", is an `ASN1_STRING` that represents a CHOICE of // several string or string-like types, such as X.509's DirectoryString. The -// |ASN1_STRING|'s type field determines which type is used. +// `ASN1_STRING`'s type field determines which type is used. // -// Multi-string types are associated with a bitmask, using the |B_ASN1_*| +// Multi-string types are associated with a bitmask, using the `B_ASN1_*` // constants, which defines which types are valid. // B_ASN1_DIRECTORYSTRING is a bitmask of types allowed in an X.509 @@ -781,16 +781,16 @@ (B_ASN1_PRINTABLESTRING | B_ASN1_TELETEXSTRING | B_ASN1_BMPSTRING | \ B_ASN1_UNIVERSALSTRING | B_ASN1_UTF8STRING) -// DIRECTORYSTRING_new returns a newly-allocated |ASN1_STRING| with type -1, or -// NULL on error. The resulting |ASN1_STRING| is not a valid X.509 +// DIRECTORYSTRING_new returns a newly-allocated `ASN1_STRING` with type -1, or +// NULL on error. The resulting `ASN1_STRING` is not a valid X.509 // DirectoryString until initialized with a value. OPENSSL_EXPORT ASN1_STRING *DIRECTORYSTRING_new(void); -// DIRECTORYSTRING_free calls |ASN1_STRING_free|. +// DIRECTORYSTRING_free calls `ASN1_STRING_free`. OPENSSL_EXPORT void DIRECTORYSTRING_free(ASN1_STRING *str); -// d2i_DIRECTORYSTRING parses up to |len| bytes from |*inp| as a DER-encoded -// X.509 DirectoryString (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_DIRECTORYSTRING parses up to `len` bytes from `*inp` as a DER-encoded +// X.509 DirectoryString (RFC 5280), as described in `d2i_SAMPLE`. // // TODO(https://crbug.com/boringssl/354): This function currently also accepts // BER, but this will be removed in the future. @@ -800,8 +800,8 @@ OPENSSL_EXPORT ASN1_STRING *d2i_DIRECTORYSTRING(ASN1_STRING **out, const uint8_t **inp, long len); -// i2d_DIRECTORYSTRING marshals |in| as a DER-encoded X.509 DirectoryString (RFC -// 5280), as described in |i2d_SAMPLE|. +// i2d_DIRECTORYSTRING marshals `in` as a DER-encoded X.509 DirectoryString (RFC +// 5280), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_DIRECTORYSTRING(const ASN1_STRING *in, uint8_t **outp); // B_ASN1_DISPLAYTEXT is a bitmask of types allowed in an X.509 DisplayText (RFC @@ -810,16 +810,16 @@ (B_ASN1_IA5STRING | B_ASN1_VISIBLESTRING | B_ASN1_BMPSTRING | \ B_ASN1_UTF8STRING) -// DISPLAYTEXT_new returns a newly-allocated |ASN1_STRING| with type -1, or NULL -// on error. The resulting |ASN1_STRING| is not a valid X.509 DisplayText until +// DISPLAYTEXT_new returns a newly-allocated `ASN1_STRING` with type -1, or NULL +// on error. The resulting `ASN1_STRING` is not a valid X.509 DisplayText until // initialized with a value. OPENSSL_EXPORT ASN1_STRING *DISPLAYTEXT_new(void); -// DISPLAYTEXT_free calls |ASN1_STRING_free|. +// DISPLAYTEXT_free calls `ASN1_STRING_free`. OPENSSL_EXPORT void DISPLAYTEXT_free(ASN1_STRING *str); -// d2i_DISPLAYTEXT parses up to |len| bytes from |*inp| as a DER-encoded X.509 -// DisplayText (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_DISPLAYTEXT parses up to `len` bytes from `*inp` as a DER-encoded X.509 +// DisplayText (RFC 5280), as described in `d2i_SAMPLE`. // // TODO(https://crbug.com/boringssl/354): This function currently also accepts // BER, but this will be removed in the future. @@ -829,8 +829,8 @@ OPENSSL_EXPORT ASN1_STRING *d2i_DISPLAYTEXT(ASN1_STRING **out, const uint8_t **inp, long len); -// i2d_DISPLAYTEXT marshals |in| as a DER-encoded X.509 DisplayText (RFC 5280), -// as described in |i2d_SAMPLE|. +// i2d_DISPLAYTEXT marshals `in` as a DER-encoded X.509 DisplayText (RFC 5280), +// as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_DISPLAYTEXT(const ASN1_STRING *in, uint8_t **outp); @@ -843,7 +843,7 @@ // Some BIT STRINGs represent a bitmask of named bits, such as the X.509 key // usage extension in RFC 5280, section 4.2.1.3. For such bit strings, DER // imposes an additional restriction that trailing zero bits are removed. Some -// functions like |ASN1_BIT_STRING_set_bit| help in maintaining this. +// functions like `ASN1_BIT_STRING_set_bit` help in maintaining this. // // Other BIT STRINGs are arbitrary strings of bits used as identifiers and do // not have this constraint, such as the X.509 issuerUniqueID field. @@ -854,50 +854,50 @@ // AlgorithmIdentifier. While some unknown algorithm could choose to store // arbitrary bit strings, all supported algorithms use a byte string, with bit // order matching the DER encoding. Callers interpreting a BIT STRING as a byte -// string should use |ASN1_BIT_STRING_num_bytes| instead of |ASN1_STRING_length| +// string should use `ASN1_BIT_STRING_num_bytes` instead of `ASN1_STRING_length` // and reject bit strings that are not a whole number of bytes. // -// This library represents BIT STRINGs as |ASN1_STRING|s with type -// |V_ASN1_BIT_STRING|. The data contains the encoded form of the BIT STRING, +// This library represents BIT STRINGs as `ASN1_STRING`s with type +// `V_ASN1_BIT_STRING`. The data contains the encoded form of the BIT STRING, // including any padding bits added to round to a whole number of bytes, but // excluding the leading byte containing the number of padding bits. Instead, -// the bottom three bits of |flags| contain the number of padding bits. For +// the bottom three bits of `flags` contain the number of padding bits. For // example, DER encodes the BIT STRING {1, 0} as {0x06, 0x80 = 0b10_000000}. The -// |ASN1_STRING| representation has data of {0x80} and flags of 6. +// `ASN1_STRING` representation has data of {0x80} and flags of 6. -// ASN1_BIT_STRING_new calls |ASN1_STRING_type_new| with |V_ASN1_BIT_STRING|. +// ASN1_BIT_STRING_new calls `ASN1_STRING_type_new` with `V_ASN1_BIT_STRING`. OPENSSL_EXPORT ASN1_BIT_STRING *ASN1_BIT_STRING_new(void); -// ASN1_BIT_STRING_free calls |ASN1_STRING_free|. +// ASN1_BIT_STRING_free calls `ASN1_STRING_free`. OPENSSL_EXPORT void ASN1_BIT_STRING_free(ASN1_BIT_STRING *str); -// d2i_ASN1_BIT_STRING parses up to |len| bytes from |*inp| as a DER-encoded -// ASN.1 BIT STRING, as described in |d2i_SAMPLE|. +// d2i_ASN1_BIT_STRING parses up to `len` bytes from `*inp` as a DER-encoded +// ASN.1 BIT STRING, as described in `d2i_SAMPLE`. OPENSSL_EXPORT ASN1_BIT_STRING *d2i_ASN1_BIT_STRING(ASN1_BIT_STRING **out, const uint8_t **inp, long len); -// i2d_ASN1_BIT_STRING marshals |in| as a DER-encoded ASN.1 BIT STRING, as -// described in |i2d_SAMPLE|. +// i2d_ASN1_BIT_STRING marshals `in` as a DER-encoded ASN.1 BIT STRING, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_BIT_STRING(const ASN1_BIT_STRING *in, uint8_t **outp); -// c2i_ASN1_BIT_STRING decodes |len| bytes from |*inp| as the contents of a +// c2i_ASN1_BIT_STRING decodes `len` bytes from `*inp` as the contents of a // DER-encoded BIT STRING, excluding the tag and length. It behaves like -// |d2i_SAMPLE| except, on success, it always consumes all |len| bytes. +// `d2i_SAMPLE` except, on success, it always consumes all `len` bytes. OPENSSL_EXPORT ASN1_BIT_STRING *c2i_ASN1_BIT_STRING(ASN1_BIT_STRING **out, const uint8_t **inp, long len); -// i2c_ASN1_BIT_STRING encodes |in| as the contents of a DER-encoded BIT STRING, -// excluding the tag and length. If |outp| is non-NULL, it writes the result to -// |*outp|, advances |*outp| just past the output, and returns the number of -// bytes written. |*outp| must have space available for the result. If |outp| is +// i2c_ASN1_BIT_STRING encodes `in` as the contents of a DER-encoded BIT STRING, +// excluding the tag and length. If `outp` is non-NULL, it writes the result to +// `*outp`, advances `*outp` just past the output, and returns the number of +// bytes written. `*outp` must have space available for the result. If `outp` is // NULL, it returns the number of bytes without writing anything. On error, it // returns a value <= 0. // -// Note this function differs slightly from |i2d_SAMPLE|. If |outp| is non-NULL -// and |*outp| is NULL, it does not allocate a new buffer. +// Note this function differs slightly from `i2d_SAMPLE`. If `outp` is non-NULL +// and `*outp` is NULL, it does not allocate a new buffer. // // TODO(davidben): This function currently returns zero on error instead of -1, // but it is also mostly infallible. I've currently documented <= 0 to suggest @@ -905,44 +905,44 @@ OPENSSL_EXPORT int i2c_ASN1_BIT_STRING(const ASN1_BIT_STRING *in, uint8_t **outp); -// ASN1_BIT_STRING is an |ASN1_ITEM| with ASN.1 type BIT STRING and C type -// |ASN1_BIT_STRING*|. +// ASN1_BIT_STRING is an `ASN1_ITEM` with ASN.1 type BIT STRING and C type +// `ASN1_BIT_STRING*`. DECLARE_ASN1_ITEM(ASN1_BIT_STRING) // ASN1_BIT_STRING_unused_bits returns the number of unused bits in the last -// byte of |str|. If |str| is empty (i.e. |ASN1_STRING_length| is zero), this +// byte of `str`. If `str` is empty (i.e. `ASN1_STRING_length` is zero), this // always returns zero. Otherwise it returns a number between 0 and 7. OPENSSL_EXPORT uint8_t ASN1_BIT_STRING_unused_bits(const ASN1_BIT_STRING *str); -// ASN1_BIT_STRING_set calls |ASN1_STRING_set|. +// ASN1_BIT_STRING_set calls `ASN1_STRING_set`. OPENSSL_EXPORT int ASN1_BIT_STRING_set(ASN1_BIT_STRING *str, const uint8_t *data, ossl_ssize_t length); -// ASN1_BIT_STRING_set1 sets |str| to a BIT STRING containing |length| bytes -// from |data|. It returns one on success and zero on error. The least -// significant |unused_bits| of the last byte of |data| are removed from the bit -// string. The removed bits must all be zero. |unused_bits| must be between 0 -// and 7, and must be 0 if |length| is zero. +// ASN1_BIT_STRING_set1 sets `str` to a BIT STRING containing `length` bytes +// from `data`. It returns one on success and zero on error. The least +// significant `unused_bits` of the last byte of `data` are removed from the bit +// string. The removed bits must all be zero. `unused_bits` must be between 0 +// and 7, and must be 0 if `length` is zero. OPENSSL_EXPORT int ASN1_BIT_STRING_set1(ASN1_BIT_STRING *str, const uint8_t *data, size_t length, int unused_bits); -// ASN1_BIT_STRING_set_bit sets bit |n| of |str| to one if |value| is non-zero -// and zero if |value| is zero, resizing |str| as needed. It then truncates -// trailing zeros in |str| to align with the DER representation for a bit string -// with named bits. It returns one on success and zero on error. |n| is indexed +// ASN1_BIT_STRING_set_bit sets bit `n` of `str` to one if `value` is non-zero +// and zero if `value` is zero, resizing `str` as needed. It then truncates +// trailing zeros in `str` to align with the DER representation for a bit string +// with named bits. It returns one on success and zero on error. `n` is indexed // beginning from zero. OPENSSL_EXPORT int ASN1_BIT_STRING_set_bit(ASN1_BIT_STRING *str, int n, int value); -// ASN1_BIT_STRING_get_bit returns one if bit |n| of |a| is in bounds and set, -// and zero otherwise. |n| is indexed beginning from zero. +// ASN1_BIT_STRING_get_bit returns one if bit `n` of `a` is in bounds and set, +// and zero otherwise. `n` is indexed beginning from zero. OPENSSL_EXPORT int ASN1_BIT_STRING_get_bit(const ASN1_BIT_STRING *str, int n); -// ASN1_BIT_STRING_check returns one if |str| only contains bits that are set in -// the |flags_len| bytes pointed by |flags|. Otherwise it returns zero. Bits in -// |flags| are arranged according to the DER representation, so bit 0 -// corresponds to the MSB of |flags[0]|. +// ASN1_BIT_STRING_check returns one if `str` only contains bits that are set in +// the `flags_len` bytes pointed by `flags`. Otherwise it returns zero. Bits in +// `flags` are arranged according to the DER representation, so bit 0 +// corresponds to the MSB of `flags[0]`. OPENSSL_EXPORT int ASN1_BIT_STRING_check(const ASN1_BIT_STRING *str, const unsigned char *flags, int flags_len); @@ -950,162 +950,162 @@ // Integers and enumerated values. // -// INTEGER and ENUMERATED values are represented as |ASN1_STRING|s where the +// INTEGER and ENUMERATED values are represented as `ASN1_STRING`s where the // data contains the big-endian encoding of the absolute value of the integer. // The sign bit is encoded in the type: non-negative values have a type of -// |V_ASN1_INTEGER| or |V_ASN1_ENUMERATED|, while negative values have a type of -// |V_ASN1_NEG_INTEGER| or |V_ASN1_NEG_ENUMERATED|. Note this differs from DER's +// `V_ASN1_INTEGER` or `V_ASN1_ENUMERATED`, while negative values have a type of +// `V_ASN1_NEG_INTEGER` or `V_ASN1_NEG_ENUMERATED`. Note this differs from DER's // two's complement representation. // -// The data in the |ASN1_STRING| may not have leading zeros. Note this means +// The data in the `ASN1_STRING` may not have leading zeros. Note this means // zero is represented as the empty string. Parsing functions will never return // invalid representations. If an invalid input is constructed, the marshaling // functions will skip leading zeros, however other functions, such as -// |ASN1_INTEGER_cmp| or |ASN1_INTEGER_get|, may not return the correct result. +// `ASN1_INTEGER_cmp` or `ASN1_INTEGER_get`, may not return the correct result. DEFINE_STACK_OF(ASN1_INTEGER) -// ASN1_INTEGER_new calls |ASN1_STRING_type_new| with |V_ASN1_INTEGER|. The +// ASN1_INTEGER_new calls `ASN1_STRING_type_new` with `V_ASN1_INTEGER`. The // resulting object has value zero. OPENSSL_EXPORT ASN1_INTEGER *ASN1_INTEGER_new(void); -// ASN1_INTEGER_free calls |ASN1_STRING_free|. +// ASN1_INTEGER_free calls `ASN1_STRING_free`. OPENSSL_EXPORT void ASN1_INTEGER_free(ASN1_INTEGER *str); -// ASN1_INTEGER_dup calls |ASN1_STRING_dup|. +// ASN1_INTEGER_dup calls `ASN1_STRING_dup`. OPENSSL_EXPORT ASN1_INTEGER *ASN1_INTEGER_dup(const ASN1_INTEGER *x); -// d2i_ASN1_INTEGER parses up to |len| bytes from |*inp| as a DER-encoded -// ASN.1 INTEGER, as described in |d2i_SAMPLE|. +// d2i_ASN1_INTEGER parses up to `len` bytes from `*inp` as a DER-encoded +// ASN.1 INTEGER, as described in `d2i_SAMPLE`. OPENSSL_EXPORT ASN1_INTEGER *d2i_ASN1_INTEGER(ASN1_INTEGER **out, const uint8_t **inp, long len); -// i2d_ASN1_INTEGER marshals |in| as a DER-encoded ASN.1 INTEGER, as -// described in |i2d_SAMPLE|. +// i2d_ASN1_INTEGER marshals `in` as a DER-encoded ASN.1 INTEGER, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_INTEGER(const ASN1_INTEGER *in, uint8_t **outp); -// c2i_ASN1_INTEGER decodes |len| bytes from |*inp| as the contents of a +// c2i_ASN1_INTEGER decodes `len` bytes from `*inp` as the contents of a // DER-encoded INTEGER, excluding the tag and length. It behaves like -// |d2i_SAMPLE| except, on success, it always consumes all |len| bytes. +// `d2i_SAMPLE` except, on success, it always consumes all `len` bytes. OPENSSL_EXPORT ASN1_INTEGER *c2i_ASN1_INTEGER(ASN1_INTEGER **in, const uint8_t **outp, long len); -// i2c_ASN1_INTEGER encodes |in| as the contents of a DER-encoded INTEGER, -// excluding the tag and length. If |outp| is non-NULL, it writes the result to -// |*outp|, advances |*outp| just past the output, and returns the number of -// bytes written. |*outp| must have space available for the result. If |outp| is +// i2c_ASN1_INTEGER encodes `in` as the contents of a DER-encoded INTEGER, +// excluding the tag and length. If `outp` is non-NULL, it writes the result to +// `*outp`, advances `*outp` just past the output, and returns the number of +// bytes written. `*outp` must have space available for the result. If `outp` is // NULL, it returns the number of bytes without writing anything. On error, it // returns a value <= 0. // -// Note this function differs slightly from |i2d_SAMPLE|. If |outp| is non-NULL -// and |*outp| is NULL, it does not allocate a new buffer. +// Note this function differs slightly from `i2d_SAMPLE`. If `outp` is non-NULL +// and `*outp` is NULL, it does not allocate a new buffer. // // TODO(davidben): This function currently returns zero on error instead of -1, // but it is also mostly infallible. I've currently documented <= 0 to suggest // callers work with both. OPENSSL_EXPORT int i2c_ASN1_INTEGER(const ASN1_INTEGER *in, uint8_t **outp); -// ASN1_INTEGER is an |ASN1_ITEM| with ASN.1 type INTEGER and C type -// |ASN1_INTEGER*|. +// ASN1_INTEGER is an `ASN1_ITEM` with ASN.1 type INTEGER and C type +// `ASN1_INTEGER*`. DECLARE_ASN1_ITEM(ASN1_INTEGER) -// ASN1_INTEGER_set_uint64 sets |a| to an INTEGER with value |v|. It returns one +// ASN1_INTEGER_set_uint64 sets `a` to an INTEGER with value `v`. It returns one // on success and zero on error. OPENSSL_EXPORT int ASN1_INTEGER_set_uint64(ASN1_INTEGER *out, uint64_t v); -// ASN1_INTEGER_set_int64 sets |a| to an INTEGER with value |v|. It returns one +// ASN1_INTEGER_set_int64 sets `a` to an INTEGER with value `v`. It returns one // on success and zero on error. OPENSSL_EXPORT int ASN1_INTEGER_set_int64(ASN1_INTEGER *out, int64_t v); -// ASN1_INTEGER_get_uint64 converts |a| to a |uint64_t|. On success, it returns -// one and sets |*out| to the result. If |a| did not fit or has the wrong type, +// ASN1_INTEGER_get_uint64 converts `a` to a `uint64_t`. On success, it returns +// one and sets `*out` to the result. If `a` did not fit or has the wrong type, // it returns zero. OPENSSL_EXPORT int ASN1_INTEGER_get_uint64(uint64_t *out, const ASN1_INTEGER *a); -// ASN1_INTEGER_get_int64 converts |a| to a |int64_t|. On success, it returns -// one and sets |*out| to the result. If |a| did not fit or has the wrong type, +// ASN1_INTEGER_get_int64 converts `a` to a `int64_t`. On success, it returns +// one and sets `*out` to the result. If `a` did not fit or has the wrong type, // it returns zero. OPENSSL_EXPORT int ASN1_INTEGER_get_int64(int64_t *out, const ASN1_INTEGER *a); -// BN_to_ASN1_INTEGER sets |ai| to an INTEGER with value |bn| and returns |ai| -// on success or NULL or error. If |ai| is NULL, it returns a newly-allocated -// |ASN1_INTEGER| on success instead, which the caller must release with -// |ASN1_INTEGER_free|. +// BN_to_ASN1_INTEGER sets `ai` to an INTEGER with value `bn` and returns `ai` +// on success or NULL or error. If `ai` is NULL, it returns a newly-allocated +// `ASN1_INTEGER` on success instead, which the caller must release with +// `ASN1_INTEGER_free`. OPENSSL_EXPORT ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai); -// ASN1_INTEGER_to_BN sets |bn| to the value of |ai| and returns |bn| on success -// or NULL or error. If |bn| is NULL, it returns a newly-allocated |BIGNUM| on -// success instead, which the caller must release with |BN_free|. +// ASN1_INTEGER_to_BN sets `bn` to the value of `ai` and returns `bn` on success +// or NULL or error. If `bn` is NULL, it returns a newly-allocated `BIGNUM` on +// success instead, which the caller must release with `BN_free`. OPENSSL_EXPORT BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn); -// ASN1_INTEGER_cmp compares the values of |x| and |y|. It returns an integer -// equal to, less than, or greater than zero if |x| is equal to, less than, or -// greater than |y|, respectively. +// ASN1_INTEGER_cmp compares the values of `x` and `y`. It returns an integer +// equal to, less than, or greater than zero if `x` is equal to, less than, or +// greater than `y`, respectively. OPENSSL_EXPORT int ASN1_INTEGER_cmp(const ASN1_INTEGER *x, const ASN1_INTEGER *y); -// ASN1_ENUMERATED_new calls |ASN1_STRING_type_new| with |V_ASN1_ENUMERATED|. +// ASN1_ENUMERATED_new calls `ASN1_STRING_type_new` with `V_ASN1_ENUMERATED`. // The resulting object has value zero. OPENSSL_EXPORT ASN1_ENUMERATED *ASN1_ENUMERATED_new(void); -// ASN1_ENUMERATED_free calls |ASN1_STRING_free|. +// ASN1_ENUMERATED_free calls `ASN1_STRING_free`. OPENSSL_EXPORT void ASN1_ENUMERATED_free(ASN1_ENUMERATED *str); -// d2i_ASN1_ENUMERATED parses up to |len| bytes from |*inp| as a DER-encoded -// ASN.1 ENUMERATED, as described in |d2i_SAMPLE|. +// d2i_ASN1_ENUMERATED parses up to `len` bytes from `*inp` as a DER-encoded +// ASN.1 ENUMERATED, as described in `d2i_SAMPLE`. OPENSSL_EXPORT ASN1_ENUMERATED *d2i_ASN1_ENUMERATED(ASN1_ENUMERATED **out, const uint8_t **inp, long len); -// i2d_ASN1_ENUMERATED marshals |in| as a DER-encoded ASN.1 ENUMERATED, as -// described in |i2d_SAMPLE|. +// i2d_ASN1_ENUMERATED marshals `in` as a DER-encoded ASN.1 ENUMERATED, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_ENUMERATED(const ASN1_ENUMERATED *in, uint8_t **outp); -// ASN1_ENUMERATED is an |ASN1_ITEM| with ASN.1 type ENUMERATED and C type -// |ASN1_ENUMERATED*|. +// ASN1_ENUMERATED is an `ASN1_ITEM` with ASN.1 type ENUMERATED and C type +// `ASN1_ENUMERATED*`. DECLARE_ASN1_ITEM(ASN1_ENUMERATED) -// ASN1_ENUMERATED_set_uint64 sets |a| to an ENUMERATED with value |v|. It +// ASN1_ENUMERATED_set_uint64 sets `a` to an ENUMERATED with value `v`. It // returns one on success and zero on error. OPENSSL_EXPORT int ASN1_ENUMERATED_set_uint64(ASN1_ENUMERATED *out, uint64_t v); -// ASN1_ENUMERATED_set_int64 sets |a| to an ENUMERATED with value |v|. It +// ASN1_ENUMERATED_set_int64 sets `a` to an ENUMERATED with value `v`. It // returns one on success and zero on error. OPENSSL_EXPORT int ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *out, int64_t v); -// ASN1_ENUMERATED_get_uint64 converts |a| to a |uint64_t|. On success, it -// returns one and sets |*out| to the result. If |a| did not fit or has the +// ASN1_ENUMERATED_get_uint64 converts `a` to a `uint64_t`. On success, it +// returns one and sets `*out` to the result. If `a` did not fit or has the // wrong type, it returns zero. OPENSSL_EXPORT int ASN1_ENUMERATED_get_uint64(uint64_t *out, const ASN1_ENUMERATED *a); -// ASN1_ENUMERATED_get_int64 converts |a| to a |int64_t|. On success, it -// returns one and sets |*out| to the result. If |a| did not fit or has the +// ASN1_ENUMERATED_get_int64 converts `a` to a `int64_t`. On success, it +// returns one and sets `*out` to the result. If `a` did not fit or has the // wrong type, it returns zero. OPENSSL_EXPORT int ASN1_ENUMERATED_get_int64(int64_t *out, const ASN1_ENUMERATED *a); -// BN_to_ASN1_ENUMERATED sets |ai| to an ENUMERATED with value |bn| and returns -// |ai| on success or NULL or error. If |ai| is NULL, it returns a -// newly-allocated |ASN1_ENUMERATED| on success instead, which the caller must -// release with |ASN1_ENUMERATED_free|. +// BN_to_ASN1_ENUMERATED sets `ai` to an ENUMERATED with value `bn` and returns +// `ai` on success or NULL or error. If `ai` is NULL, it returns a +// newly-allocated `ASN1_ENUMERATED` on success instead, which the caller must +// release with `ASN1_ENUMERATED_free`. OPENSSL_EXPORT ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(const BIGNUM *bn, ASN1_ENUMERATED *ai); -// ASN1_ENUMERATED_to_BN sets |bn| to the value of |ai| and returns |bn| on -// success or NULL or error. If |bn| is NULL, it returns a newly-allocated -// |BIGNUM| on success instead, which the caller must release with |BN_free|. +// ASN1_ENUMERATED_to_BN sets `bn` to the value of `ai` and returns `bn` on +// success or NULL or error. If `bn` is NULL, it returns a newly-allocated +// `BIGNUM` on success instead, which the caller must release with `BN_free`. OPENSSL_EXPORT BIGNUM *ASN1_ENUMERATED_to_BN(const ASN1_ENUMERATED *ai, BIGNUM *bn); // Time. // -// GeneralizedTime and UTCTime values are represented as |ASN1_STRING|s. The -// type field is |V_ASN1_GENERALIZEDTIME| or |V_ASN1_UTCTIME|, respectively. The +// GeneralizedTime and UTCTime values are represented as `ASN1_STRING`s. The +// type field is `V_ASN1_GENERALIZEDTIME` or `V_ASN1_UTCTIME`, respectively. The // data field contains the DER encoding of the value. For example, the UNIX // epoch would be "19700101000000Z" for a GeneralizedTime and "700101000000Z" // for a UTCTime. @@ -1116,49 +1116,49 @@ // BER, and the additional restrictions from RFC 5280, but future versions may. // Callers should not rely on fractional seconds and non-UTC time zones. // -// The |ASN1_TIME| typedef is a multi-string representing the X.509 Time type, +// The `ASN1_TIME` typedef is a multi-string representing the X.509 Time type, // which is a CHOICE of GeneralizedTime and UTCTime, using UTCTime when the // value is in range. -// ASN1_UTCTIME_new calls |ASN1_STRING_type_new| with |V_ASN1_UTCTIME|. The +// ASN1_UTCTIME_new calls `ASN1_STRING_type_new` with `V_ASN1_UTCTIME`. The // resulting object contains empty contents and must be initialized to be a // valid UTCTime. OPENSSL_EXPORT ASN1_UTCTIME *ASN1_UTCTIME_new(void); -// ASN1_UTCTIME_free calls |ASN1_STRING_free|. +// ASN1_UTCTIME_free calls `ASN1_STRING_free`. OPENSSL_EXPORT void ASN1_UTCTIME_free(ASN1_UTCTIME *str); -// d2i_ASN1_UTCTIME parses up to |len| bytes from |*inp| as a DER-encoded -// ASN.1 UTCTime, as described in |d2i_SAMPLE|. +// d2i_ASN1_UTCTIME parses up to `len` bytes from `*inp` as a DER-encoded +// ASN.1 UTCTime, as described in `d2i_SAMPLE`. // // TODO(https://crbug.com/boringssl/354): This function currently also accepts // BER, but this will be removed in the future. OPENSSL_EXPORT ASN1_UTCTIME *d2i_ASN1_UTCTIME(ASN1_UTCTIME **out, const uint8_t **inp, long len); -// i2d_ASN1_UTCTIME marshals |in| as a DER-encoded ASN.1 UTCTime, as -// described in |i2d_SAMPLE|. +// i2d_ASN1_UTCTIME marshals `in` as a DER-encoded ASN.1 UTCTime, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_UTCTIME(const ASN1_UTCTIME *in, uint8_t **outp); -// ASN1_UTCTIME is an |ASN1_ITEM| with ASN.1 type UTCTime and C type -// |ASN1_UTCTIME*|. +// ASN1_UTCTIME is an `ASN1_ITEM` with ASN.1 type UTCTime and C type +// `ASN1_UTCTIME*`. DECLARE_ASN1_ITEM(ASN1_UTCTIME) -// ASN1_UTCTIME_check returns one if |a| is a valid UTCTime and zero otherwise. +// ASN1_UTCTIME_check returns one if `a` is a valid UTCTime and zero otherwise. OPENSSL_EXPORT int ASN1_UTCTIME_check(const ASN1_UTCTIME *a); -// ASN1_UTCTIME_set represents |posix_time| as a UTCTime and writes the result -// to |s|. It returns |s| on success and NULL on error. If |s| is NULL, it -// returns a newly-allocated |ASN1_UTCTIME| instead. +// ASN1_UTCTIME_set represents `posix_time` as a UTCTime and writes the result +// to `s`. It returns `s` on success and NULL on error. If `s` is NULL, it +// returns a newly-allocated `ASN1_UTCTIME` instead. // // Note this function may fail if the time is out of range for UTCTime. OPENSSL_EXPORT ASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, int64_t posix_time); -// ASN1_UTCTIME_adj adds |offset_day| days and |offset_sec| seconds to -// |posix_time| and writes the result to |s| as a UTCTime. It returns |s| on -// success and NULL on error. If |s| is NULL, it returns a newly-allocated -// |ASN1_UTCTIME| instead. +// ASN1_UTCTIME_adj adds `offset_day` days and `offset_sec` seconds to +// `posix_time` and writes the result to `s` as a UTCTime. It returns `s` on +// success and NULL on error. If `s` is NULL, it returns a newly-allocated +// `ASN1_UTCTIME` instead. // // Note this function may fail if the time overflows or is out of range for // UTCTime. @@ -1166,51 +1166,51 @@ int64_t posix_time, int offset_day, long offset_sec); -// ASN1_UTCTIME_set_string sets |s| to a UTCTime whose contents are a copy of -// |str|. It returns one on success and zero on error or if |str| is not a valid +// ASN1_UTCTIME_set_string sets `s` to a UTCTime whose contents are a copy of +// `str`. It returns one on success and zero on error or if `str` is not a valid // UTCTime. // -// If |s| is NULL, this function validates |str| without copying it. +// If `s` is NULL, this function validates `str` without copying it. OPENSSL_EXPORT int ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str); -// ASN1_GENERALIZEDTIME_new calls |ASN1_STRING_type_new| with -// |V_ASN1_GENERALIZEDTIME|. The resulting object contains empty contents and +// ASN1_GENERALIZEDTIME_new calls `ASN1_STRING_type_new` with +// `V_ASN1_GENERALIZEDTIME`. The resulting object contains empty contents and // must be initialized to be a valid GeneralizedTime. OPENSSL_EXPORT ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_new(void); -// ASN1_GENERALIZEDTIME_free calls |ASN1_STRING_free|. +// ASN1_GENERALIZEDTIME_free calls `ASN1_STRING_free`. OPENSSL_EXPORT void ASN1_GENERALIZEDTIME_free(ASN1_GENERALIZEDTIME *str); -// d2i_ASN1_GENERALIZEDTIME parses up to |len| bytes from |*inp| as a -// DER-encoded ASN.1 GeneralizedTime, as described in |d2i_SAMPLE|. +// d2i_ASN1_GENERALIZEDTIME parses up to `len` bytes from `*inp` as a +// DER-encoded ASN.1 GeneralizedTime, as described in `d2i_SAMPLE`. OPENSSL_EXPORT ASN1_GENERALIZEDTIME *d2i_ASN1_GENERALIZEDTIME( ASN1_GENERALIZEDTIME **out, const uint8_t **inp, long len); -// i2d_ASN1_GENERALIZEDTIME marshals |in| as a DER-encoded ASN.1 -// GeneralizedTime, as described in |i2d_SAMPLE|. +// i2d_ASN1_GENERALIZEDTIME marshals `in` as a DER-encoded ASN.1 +// GeneralizedTime, as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_GENERALIZEDTIME(const ASN1_GENERALIZEDTIME *in, uint8_t **outp); -// ASN1_GENERALIZEDTIME is an |ASN1_ITEM| with ASN.1 type GeneralizedTime and C -// type |ASN1_GENERALIZEDTIME*|. +// ASN1_GENERALIZEDTIME is an `ASN1_ITEM` with ASN.1 type GeneralizedTime and C +// type `ASN1_GENERALIZEDTIME*`. DECLARE_ASN1_ITEM(ASN1_GENERALIZEDTIME) -// ASN1_GENERALIZEDTIME_check returns one if |a| is a valid GeneralizedTime and +// ASN1_GENERALIZEDTIME_check returns one if `a` is a valid GeneralizedTime and // zero otherwise. OPENSSL_EXPORT int ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *a); -// ASN1_GENERALIZEDTIME_set represents |posix_time| as a GeneralizedTime and -// writes the result to |s|. It returns |s| on success and NULL on error. If |s| -// is NULL, it returns a newly-allocated |ASN1_GENERALIZEDTIME| instead. +// ASN1_GENERALIZEDTIME_set represents `posix_time` as a GeneralizedTime and +// writes the result to `s`. It returns `s` on success and NULL on error. If `s` +// is NULL, it returns a newly-allocated `ASN1_GENERALIZEDTIME` instead. // // Note this function may fail if the time is out of range for GeneralizedTime. OPENSSL_EXPORT ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set( ASN1_GENERALIZEDTIME *s, int64_t posix_time); -// ASN1_GENERALIZEDTIME_adj adds |offset_day| days and |offset_sec| seconds to -// |posix_time| and writes the result to |s| as a GeneralizedTime. It returns -// |s| on success and NULL on error. If |s| is NULL, it returns a -// newly-allocated |ASN1_GENERALIZEDTIME| instead. +// ASN1_GENERALIZEDTIME_adj adds `offset_day` days and `offset_sec` seconds to +// `posix_time` and writes the result to `s` as a GeneralizedTime. It returns +// `s` on success and NULL on error. If `s` is NULL, it returns a +// newly-allocated `ASN1_GENERALIZEDTIME` instead. // // Note this function may fail if the time overflows or is out of range for // GeneralizedTime. @@ -1218,110 +1218,110 @@ ASN1_GENERALIZEDTIME *s, int64_t posix_time, int offset_day, long offset_sec); -// ASN1_GENERALIZEDTIME_set_string sets |s| to a GeneralizedTime whose contents -// are a copy of |str|. It returns one on success and zero on error or if |str| +// ASN1_GENERALIZEDTIME_set_string sets `s` to a GeneralizedTime whose contents +// are a copy of `str`. It returns one on success and zero on error or if `str` // is not a valid GeneralizedTime. // -// If |s| is NULL, this function validates |str| without copying it. +// If `s` is NULL, this function validates `str` without copying it. OPENSSL_EXPORT int ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s, const char *str); // B_ASN1_TIME is a bitmask of types allowed in an X.509 Time. #define B_ASN1_TIME (B_ASN1_UTCTIME | B_ASN1_GENERALIZEDTIME) -// ASN1_TIME_new returns a newly-allocated |ASN1_TIME| with type -1, or NULL on -// error. The resulting |ASN1_TIME| is not a valid X.509 Time until initialized +// ASN1_TIME_new returns a newly-allocated `ASN1_TIME` with type -1, or NULL on +// error. The resulting `ASN1_TIME` is not a valid X.509 Time until initialized // with a value. OPENSSL_EXPORT ASN1_TIME *ASN1_TIME_new(void); -// ASN1_TIME_free releases memory associated with |str|. +// ASN1_TIME_free releases memory associated with `str`. OPENSSL_EXPORT void ASN1_TIME_free(ASN1_TIME *str); -// d2i_ASN1_TIME parses up to |len| bytes from |*inp| as a DER-encoded X.509 -// Time (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_ASN1_TIME parses up to `len` bytes from `*inp` as a DER-encoded X.509 +// Time (RFC 5280), as described in `d2i_SAMPLE`. // // TODO(https://crbug.com/boringssl/354): This function currently also accepts // BER, but this will be removed in the future. OPENSSL_EXPORT ASN1_TIME *d2i_ASN1_TIME(ASN1_TIME **out, const uint8_t **inp, long len); -// i2d_ASN1_TIME marshals |in| as a DER-encoded X.509 Time (RFC 5280), as -// described in |i2d_SAMPLE|. +// i2d_ASN1_TIME marshals `in` as a DER-encoded X.509 Time (RFC 5280), as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_TIME(const ASN1_TIME *in, uint8_t **outp); -// ASN1_TIME_diff computes |to| - |from|. On success, it sets |*out_days| to the -// difference in days, rounded towards zero, sets |*out_seconds| to the +// ASN1_TIME_diff computes `to` - `from`. On success, it sets `*out_days` to the +// difference in days, rounded towards zero, sets `*out_seconds` to the // remainder, and returns one. On error, it returns zero. // -// If |from| is before |to|, both outputs will be <= 0, with at least one -// negative. If |from| is after |to|, both will be >= 0, with at least one +// If `from` is before `to`, both outputs will be <= 0, with at least one +// negative. If `from` is after `to`, both will be >= 0, with at least one // positive. If they are equal, ignoring fractional seconds, both will be zero. // -// Note this function may fail on overflow, or if |from| or |to| cannot be +// Note this function may fail on overflow, or if `from` or `to` cannot be // decoded. OPENSSL_EXPORT int ASN1_TIME_diff(int *out_days, int *out_seconds, const ASN1_TIME *from, const ASN1_TIME *to); -// ASN1_TIME_set_posix represents |posix_time| as a GeneralizedTime or UTCTime -// and writes the result to |s|. As in RFC 5280, section 4.1.2.5, it uses -// UTCTime when the time fits and GeneralizedTime otherwise. It returns |s| on -// success and NULL on error. If |s| is NULL, it returns a newly-allocated -// |ASN1_TIME| instead. +// ASN1_TIME_set_posix represents `posix_time` as a GeneralizedTime or UTCTime +// and writes the result to `s`. As in RFC 5280, section 4.1.2.5, it uses +// UTCTime when the time fits and GeneralizedTime otherwise. It returns `s` on +// success and NULL on error. If `s` is NULL, it returns a newly-allocated +// `ASN1_TIME` instead. // // Note this function may fail if the time is out of range for GeneralizedTime. OPENSSL_EXPORT ASN1_TIME *ASN1_TIME_set_posix(ASN1_TIME *s, int64_t posix_time); -// ASN1_TIME_set is exactly the same as |ASN1_TIME_set_posix| but with a +// ASN1_TIME_set is exactly the same as `ASN1_TIME_set_posix` but with a // time_t as input for compatibility. OPENSSL_EXPORT ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t time); -// ASN1_TIME_adj adds |offset_day| days and |offset_sec| seconds to -// |posix_time| and writes the result to |s|. As in RFC 5280, section 4.1.2.5, +// ASN1_TIME_adj adds `offset_day` days and `offset_sec` seconds to +// `posix_time` and writes the result to `s`. As in RFC 5280, section 4.1.2.5, // it uses UTCTime when the time fits and GeneralizedTime otherwise. It returns -// |s| on success and NULL on error. If |s| is NULL, it returns a -// newly-allocated |ASN1_GENERALIZEDTIME| instead. +// `s` on success and NULL on error. If `s` is NULL, it returns a +// newly-allocated `ASN1_GENERALIZEDTIME` instead. // // Note this function may fail if the time overflows or is out of range for // GeneralizedTime. OPENSSL_EXPORT ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, int64_t posix_time, int offset_day, long offset_sec); -// ASN1_TIME_check returns one if |t| is a valid UTCTime or GeneralizedTime, and -// zero otherwise. |t|'s type determines which check is performed. This +// ASN1_TIME_check returns one if `t` is a valid UTCTime or GeneralizedTime, and +// zero otherwise. `t`'s type determines which check is performed. This // function does not enforce that UTCTime was used when possible. OPENSSL_EXPORT int ASN1_TIME_check(const ASN1_TIME *t); -// ASN1_TIME_to_generalizedtime converts |t| to a GeneralizedTime. If |out| is -// NULL, it returns a newly-allocated |ASN1_GENERALIZEDTIME| on success, or NULL -// on error. If |out| is non-NULL and |*out| is NULL, it additionally sets -// |*out| to the result. If |out| and |*out| are non-NULL, it instead updates -// the object pointed by |*out| and returns |*out| on success or NULL on error. +// ASN1_TIME_to_generalizedtime converts `t` to a GeneralizedTime. If `out` is +// NULL, it returns a newly-allocated `ASN1_GENERALIZEDTIME` on success, or NULL +// on error. If `out` is non-NULL and `*out` is NULL, it additionally sets +// `*out` to the result. If `out` and `*out` are non-NULL, it instead updates +// the object pointed by `*out` and returns `*out` on success or NULL on error. OPENSSL_EXPORT ASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime( const ASN1_TIME *t, ASN1_GENERALIZEDTIME **out); -// ASN1_TIME_set_string behaves like |ASN1_UTCTIME_set_string| if |str| is a -// valid UTCTime, and |ASN1_GENERALIZEDTIME_set_string| if |str| is a valid -// GeneralizedTime. If |str| is neither, it returns zero. +// ASN1_TIME_set_string behaves like `ASN1_UTCTIME_set_string` if `str` is a +// valid UTCTime, and `ASN1_GENERALIZEDTIME_set_string` if `str` is a valid +// GeneralizedTime. If `str` is neither, it returns zero. OPENSSL_EXPORT int ASN1_TIME_set_string(ASN1_TIME *s, const char *str); -// ASN1_TIME_set_string_X509 behaves like |ASN1_TIME_set_string| except it +// ASN1_TIME_set_string_X509 behaves like `ASN1_TIME_set_string` except it // additionally converts GeneralizedTime to UTCTime if it is in the range where // UTCTime is used. See RFC 5280, section 4.1.2.5. OPENSSL_EXPORT int ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str); -// ASN1_TIME_to_time_t converts |t| to a time_t value in |out|. On +// ASN1_TIME_to_time_t converts `t` to a time_t value in `out`. On // success, one is returned. On failure, zero is returned. This function // will fail if the time can not be represented in a time_t. OPENSSL_EXPORT int ASN1_TIME_to_time_t(const ASN1_TIME *t, time_t *out); -// ASN1_TIME_to_posix converts |t| to a POSIX time value in |out|. On +// ASN1_TIME_to_posix converts `t` to a POSIX time value in `out`. On // success, one is returned. On failure, zero is returned. OPENSSL_EXPORT int ASN1_TIME_to_posix(const ASN1_TIME *t, int64_t *out); -// ASN1_TIME_to_posix_nonstandard converts |t| to a POSIX time value in -// |out|. It is exactly the same as |ASN1_TIME_to_posix| but allows for +// ASN1_TIME_to_posix_nonstandard converts `t` to a POSIX time value in +// `out`. It is exactly the same as `ASN1_TIME_to_posix` but allows for // non-standard four-digit timezone offsets on UTC times. On success, one is -// returned. On failure, zero is returned. |ASN1_TIME_to_posix| should normally +// returned. On failure, zero is returned. `ASN1_TIME_to_posix` should normally // be used instead of this function. OPENSSL_EXPORT int ASN1_TIME_to_posix_nonstandard( const ASN1_TIME *t, int64_t *out); @@ -1332,120 +1332,120 @@ // NULL values. // // This library represents the ASN.1 NULL value by a non-NULL pointer to the -// opaque type |ASN1_NULL|. An omitted OPTIONAL ASN.1 NULL value is a NULL -// pointer. Unlike other pointer types, it is not necessary to free |ASN1_NULL| +// opaque type `ASN1_NULL`. An omitted OPTIONAL ASN.1 NULL value is a NULL +// pointer. Unlike other pointer types, it is not necessary to free `ASN1_NULL` // pointers, but it is safe to do so. // ASN1_NULL_new returns an opaque, non-NULL pointer. It is safe to call -// |ASN1_NULL_free| on the result, but not necessary. +// `ASN1_NULL_free` on the result, but not necessary. OPENSSL_EXPORT ASN1_NULL *ASN1_NULL_new(void); // ASN1_NULL_free does nothing. OPENSSL_EXPORT void ASN1_NULL_free(ASN1_NULL *null); -// d2i_ASN1_NULL parses a DER-encoded ASN.1 NULL value from up to |len| bytes -// at |*inp|, as described in |d2i_SAMPLE|. +// d2i_ASN1_NULL parses a DER-encoded ASN.1 NULL value from up to `len` bytes +// at `*inp`, as described in `d2i_SAMPLE`. OPENSSL_EXPORT ASN1_NULL *d2i_ASN1_NULL(ASN1_NULL **out, const uint8_t **inp, long len); -// i2d_ASN1_NULL marshals |in| as a DER-encoded ASN.1 NULL value, as described -// in |i2d_SAMPLE|. +// i2d_ASN1_NULL marshals `in` as a DER-encoded ASN.1 NULL value, as described +// in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_NULL(const ASN1_NULL *in, uint8_t **outp); -// ASN1_NULL is an |ASN1_ITEM| with ASN.1 type NULL and C type |ASN1_NULL*|. +// ASN1_NULL is an `ASN1_ITEM` with ASN.1 type NULL and C type `ASN1_NULL*`. DECLARE_ASN1_ITEM(ASN1_NULL) // Object identifiers. // -// An |ASN1_OBJECT| represents a ASN.1 OBJECT IDENTIFIER. See also obj.h for -// additional functions relating to |ASN1_OBJECT|. +// An `ASN1_OBJECT` represents a ASN.1 OBJECT IDENTIFIER. See also obj.h for +// additional functions relating to `ASN1_OBJECT`. // // TODO(davidben): What's the relationship between asn1.h and obj.h? Most of -// obj.h deals with the large NID table, but then functions like |OBJ_get0_data| -// or |OBJ_dup| are general |ASN1_OBJECT| functions. +// obj.h deals with the large NID table, but then functions like `OBJ_get0_data` +// or `OBJ_dup` are general `ASN1_OBJECT` functions. DEFINE_STACK_OF(ASN1_OBJECT) -// ASN1_OBJECT_create returns a newly-allocated |ASN1_OBJECT| with |len| bytes -// from |data| as the encoded OID, or NULL on error. |data| should contain the +// ASN1_OBJECT_create returns a newly-allocated `ASN1_OBJECT` with `len` bytes +// from `data` as the encoded OID, or NULL on error. `data` should contain the // DER-encoded identifier, excluding the tag and length. // -// |nid| should be |NID_undef|. Passing a NID value that does not match |data| -// will cause some functions to misbehave. |sn| and |ln| should be NULL. If +// `nid` should be `NID_undef`. Passing a NID value that does not match `data` +// will cause some functions to misbehave. `sn` and `ln` should be NULL. If // non-NULL, they are stored as short and long names, respectively, but these -// values have no effect for |ASN1_OBJECT|s created through this function. +// values have no effect for `ASN1_OBJECT`s created through this function. // // TODO(davidben): Should we just ignore all those parameters? NIDs and names -// are only relevant for |ASN1_OBJECT|s in the obj.h table. +// are only relevant for `ASN1_OBJECT`s in the obj.h table. OPENSSL_EXPORT ASN1_OBJECT *ASN1_OBJECT_create(int nid, const uint8_t *data, size_t len, const char *sn, const char *ln); -// ASN1_OBJECT_free releases memory associated with |a|. If |a| is a static -// |ASN1_OBJECT|, returned from |OBJ_nid2obj|, this function does nothing. +// ASN1_OBJECT_free releases memory associated with `a`. If `a` is a static +// `ASN1_OBJECT`, returned from `OBJ_nid2obj`, this function does nothing. OPENSSL_EXPORT void ASN1_OBJECT_free(ASN1_OBJECT *a); -// d2i_ASN1_OBJECT parses a DER-encoded ASN.1 OBJECT IDENTIFIER from up to |len| -// bytes at |*inp|, as described in |d2i_SAMPLE|. +// d2i_ASN1_OBJECT parses a DER-encoded ASN.1 OBJECT IDENTIFIER from up to `len` +// bytes at `*inp`, as described in `d2i_SAMPLE`. OPENSSL_EXPORT ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **out, const uint8_t **inp, long len); -// i2d_ASN1_OBJECT marshals |in| as a DER-encoded ASN.1 OBJECT IDENTIFIER, as -// described in |i2d_SAMPLE|. +// i2d_ASN1_OBJECT marshals `in` as a DER-encoded ASN.1 OBJECT IDENTIFIER, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_OBJECT(const ASN1_OBJECT *in, uint8_t **outp); -// c2i_ASN1_OBJECT decodes |len| bytes from |*inp| as the contents of a +// c2i_ASN1_OBJECT decodes `len` bytes from `*inp` as the contents of a // DER-encoded OBJECT IDENTIFIER, excluding the tag and length. It behaves like -// |d2i_SAMPLE| except, on success, it always consumes all |len| bytes. +// `d2i_SAMPLE` except, on success, it always consumes all `len` bytes. OPENSSL_EXPORT ASN1_OBJECT *c2i_ASN1_OBJECT(ASN1_OBJECT **out, const uint8_t **inp, long len); -// ASN1_OBJECT is an |ASN1_ITEM| with ASN.1 type OBJECT IDENTIFIER and C type -// |ASN1_OBJECT*|. +// ASN1_OBJECT is an `ASN1_ITEM` with ASN.1 type OBJECT IDENTIFIER and C type +// `ASN1_OBJECT*`. DECLARE_ASN1_ITEM(ASN1_OBJECT) // Arbitrary elements. -// An asn1_type_st (aka |ASN1_TYPE|) represents an arbitrary ASN.1 element, -// typically used for ANY types. It contains a |type| field and a |value| union -// dependent on |type|. +// An asn1_type_st (aka `ASN1_TYPE`) represents an arbitrary ASN.1 element, +// typically used for ANY types. It contains a `type` field and a `value` union +// dependent on `type`. // // WARNING: This struct has a complex representation. Callers must not construct -// |ASN1_TYPE| values manually. Use |ASN1_TYPE_set| and |ASN1_TYPE_set1| +// `ASN1_TYPE` values manually. Use `ASN1_TYPE_set` and `ASN1_TYPE_set1` // instead. Additionally, callers performing non-trivial operations on this type -// are encouraged to use |CBS| and |CBB| from <openssl/bytestring.h>, and -// convert to or from |ASN1_TYPE| with |d2i_ASN1_TYPE| or |i2d_ASN1_TYPE|. +// are encouraged to use `CBS` and `CBB` from <openssl/bytestring.h>, and +// convert to or from `ASN1_TYPE` with `d2i_ASN1_TYPE` or `i2d_ASN1_TYPE`. // -// The |type| field corresponds to the tag of the ASN.1 element being +// The `type` field corresponds to the tag of the ASN.1 element being // represented: // -// If |type| is a |V_ASN1_*| constant for an ASN.1 string-like type, as defined -// by |ASN1_STRING|, the tag matches the constant. |value| contains an -// |ASN1_STRING| pointer (equivalently, one of the more specific typedefs). See -// |ASN1_STRING| for details on the representation. Unlike |ASN1_STRING|, -// |ASN1_TYPE| does not use the |V_ASN1_NEG| flag for negative INTEGER and -// ENUMERATE values. For a negative value, the |ASN1_TYPE|'s |type| will be -// |V_ASN1_INTEGER| or |V_ASN1_ENUMERATED|, but |value| will an |ASN1_STRING| -// whose |type| is |V_ASN1_NEG_INTEGER| or |V_ASN1_NEG_ENUMERATED|. +// If `type` is a `V_ASN1_*` constant for an ASN.1 string-like type, as defined +// by `ASN1_STRING`, the tag matches the constant. `value` contains an +// `ASN1_STRING` pointer (equivalently, one of the more specific typedefs). See +// `ASN1_STRING` for details on the representation. Unlike `ASN1_STRING`, +// `ASN1_TYPE` does not use the `V_ASN1_NEG` flag for negative INTEGER and +// ENUMERATE values. For a negative value, the `ASN1_TYPE`'s `type` will be +// `V_ASN1_INTEGER` or `V_ASN1_ENUMERATED`, but `value` will an `ASN1_STRING` +// whose `type` is `V_ASN1_NEG_INTEGER` or `V_ASN1_NEG_ENUMERATED`. // -// If |type| is |V_ASN1_OBJECT|, the tag is OBJECT IDENTIFIER and |value| -// contains an |ASN1_OBJECT| pointer. +// If `type` is `V_ASN1_OBJECT`, the tag is OBJECT IDENTIFIER and `value` +// contains an `ASN1_OBJECT` pointer. // -// If |type| is |V_ASN1_NULL|, the tag is NULL. |value| contains a NULL pointer. +// If `type` is `V_ASN1_NULL`, the tag is NULL. `value` contains a NULL pointer. // -// If |type| is |V_ASN1_BOOLEAN|, the tag is BOOLEAN. |value| contains an -// |ASN1_BOOLEAN|. +// If `type` is `V_ASN1_BOOLEAN`, the tag is BOOLEAN. `value` contains an +// `ASN1_BOOLEAN`. // -// If |type| is |V_ASN1_SEQUENCE|, |V_ASN1_SET|, or |V_ASN1_OTHER|, the tag is -// SEQUENCE, SET, or some arbitrary tag, respectively. |value| uses the -// corresponding |ASN1_STRING| representation. Although any type may be -// represented in |V_ASN1_OTHER|, the parser will always return the more +// If `type` is `V_ASN1_SEQUENCE`, `V_ASN1_SET`, or `V_ASN1_OTHER`, the tag is +// SEQUENCE, SET, or some arbitrary tag, respectively. `value` uses the +// corresponding `ASN1_STRING` representation. Although any type may be +// represented in `V_ASN1_OTHER`, the parser will always return the more // specific encoding when available. // -// Other values of |type| do not represent a valid ASN.1 value, though -// default-constructed objects may set |type| to -1. Such objects cannot be +// Other values of `type` do not represent a valid ASN.1 value, though +// default-constructed objects may set `type` to -1. Such objects cannot be // serialized. struct asn1_type_st { int type; @@ -1477,18 +1477,18 @@ DEFINE_STACK_OF(ASN1_TYPE) -// ASN1_TYPE_new returns a newly-allocated |ASN1_TYPE|, or NULL on allocation +// ASN1_TYPE_new returns a newly-allocated `ASN1_TYPE`, or NULL on allocation // failure. The resulting object has type -1 and must be initialized to be // a valid ANY value. OPENSSL_EXPORT ASN1_TYPE *ASN1_TYPE_new(void); -// ASN1_TYPE_free releases memory associated with |a|. +// ASN1_TYPE_free releases memory associated with `a`. OPENSSL_EXPORT void ASN1_TYPE_free(ASN1_TYPE *a); -// d2i_ASN1_TYPE parses up to |len| bytes from |*inp| as an ASN.1 value of any -// type, as described in |d2i_SAMPLE|. Note this function only validates +// d2i_ASN1_TYPE parses up to `len` bytes from `*inp` as an ASN.1 value of any +// type, as described in `d2i_SAMPLE`. Note this function only validates // primitive, universal types supported by this library. Values of type -// |V_ASN1_SEQUENCE|, |V_ASN1_SET|, |V_ASN1_OTHER|, or an unsupported primitive +// `V_ASN1_SEQUENCE`, `V_ASN1_SET`, `V_ASN1_OTHER`, or an unsupported primitive // type must be validated by the caller when interpreting. // // TODO(https://crbug.com/boringssl/354): This function currently also accepts @@ -1496,46 +1496,46 @@ OPENSSL_EXPORT ASN1_TYPE *d2i_ASN1_TYPE(ASN1_TYPE **out, const uint8_t **inp, long len); -// i2d_ASN1_TYPE marshals |in| as DER, as described in |i2d_SAMPLE|. +// i2d_ASN1_TYPE marshals `in` as DER, as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_TYPE(const ASN1_TYPE *in, uint8_t **outp); -// ASN1_ANY is an |ASN1_ITEM| with ASN.1 type ANY and C type |ASN1_TYPE*|. Note -// the |ASN1_ITEM| name and C type do not match. +// ASN1_ANY is an `ASN1_ITEM` with ASN.1 type ANY and C type `ASN1_TYPE*`. Note +// the `ASN1_ITEM` name and C type do not match. DECLARE_ASN1_ITEM(ASN1_ANY) -// ASN1_TYPE_get returns the type of |a|, which will be one of the |V_ASN1_*| -// constants, or zero if |a| is not fully initialized. +// ASN1_TYPE_get returns the type of `a`, which will be one of the `V_ASN1_*` +// constants, or zero if `a` is not fully initialized. OPENSSL_EXPORT int ASN1_TYPE_get(const ASN1_TYPE *a); -// ASN1_TYPE_set sets |a| to an |ASN1_TYPE| of type |type| and value |value|, -// releasing the previous contents of |a|. +// ASN1_TYPE_set sets `a` to an `ASN1_TYPE` of type `type` and value `value`, +// releasing the previous contents of `a`. // -// If |type| is |V_ASN1_BOOLEAN|, |a| is set to FALSE if |value| is NULL and -// TRUE otherwise. If setting |a| to TRUE, |value| may be an invalid pointer, +// If `type` is `V_ASN1_BOOLEAN`, `a` is set to FALSE if `value` is NULL and +// TRUE otherwise. If setting `a` to TRUE, `value` may be an invalid pointer, // such as (void*)1. // -// If |type| is |V_ASN1_NULL|, |value| must be NULL. +// If `type` is `V_ASN1_NULL`, `value` must be NULL. // -// For other values of |type|, this function takes ownership of |value|, which -// must point to an object of the corresponding type. See |ASN1_TYPE| for +// For other values of `type`, this function takes ownership of `value`, which +// must point to an object of the corresponding type. See `ASN1_TYPE` for // details. OPENSSL_EXPORT void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value); -// ASN1_TYPE_set1 behaves like |ASN1_TYPE_set| except it does not take ownership -// of |value|. It returns one on success and zero on error. +// ASN1_TYPE_set1 behaves like `ASN1_TYPE_set` except it does not take ownership +// of `value`. It returns one on success and zero on error. OPENSSL_EXPORT int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value); -// ASN1_TYPE_cmp returns zero if |a| and |b| are equal and some non-zero value +// ASN1_TYPE_cmp returns zero if `a` and `b` are equal and some non-zero value // otherwise. Note this function can only be used for equality checks, not an // ordering. OPENSSL_EXPORT int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b); typedef STACK_OF(ASN1_TYPE) ASN1_SEQUENCE_ANY; -// d2i_ASN1_SEQUENCE_ANY parses up to |len| bytes from |*inp| as a DER-encoded -// ASN.1 SEQUENCE OF ANY structure, as described in |d2i_SAMPLE|. The resulting -// |ASN1_SEQUENCE_ANY| owns its contents and thus must be released with -// |sk_ASN1_TYPE_pop_free| and |ASN1_TYPE_free|, not |sk_ASN1_TYPE_free|. +// d2i_ASN1_SEQUENCE_ANY parses up to `len` bytes from `*inp` as a DER-encoded +// ASN.1 SEQUENCE OF ANY structure, as described in `d2i_SAMPLE`. The resulting +// `ASN1_SEQUENCE_ANY` owns its contents and thus must be released with +// `sk_ASN1_TYPE_pop_free` and `ASN1_TYPE_free`, not `sk_ASN1_TYPE_free`. // // TODO(https://crbug.com/boringssl/354): This function currently also accepts // BER, but this will be removed in the future. @@ -1543,15 +1543,15 @@ const uint8_t **inp, long len); -// i2d_ASN1_SEQUENCE_ANY marshals |in| as a DER-encoded SEQUENCE OF ANY -// structure, as described in |i2d_SAMPLE|. +// i2d_ASN1_SEQUENCE_ANY marshals `in` as a DER-encoded SEQUENCE OF ANY +// structure, as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_SEQUENCE_ANY(const ASN1_SEQUENCE_ANY *in, uint8_t **outp); -// d2i_ASN1_SET_ANY parses up to |len| bytes from |*inp| as a DER-encoded ASN.1 -// SET OF ANY structure, as described in |d2i_SAMPLE|. The resulting -// |ASN1_SEQUENCE_ANY| owns its contents and thus must be released with -// |sk_ASN1_TYPE_pop_free| and |ASN1_TYPE_free|, not |sk_ASN1_TYPE_free|. +// d2i_ASN1_SET_ANY parses up to `len` bytes from `*inp` as a DER-encoded ASN.1 +// SET OF ANY structure, as described in `d2i_SAMPLE`. The resulting +// `ASN1_SEQUENCE_ANY` owns its contents and thus must be released with +// `sk_ASN1_TYPE_pop_free` and `ASN1_TYPE_free`, not `sk_ASN1_TYPE_free`. // // TODO(https://crbug.com/boringssl/354): This function currently also accepts // BER, but this will be removed in the future. @@ -1559,8 +1559,8 @@ const uint8_t **inp, long len); -// i2d_ASN1_SET_ANY marshals |in| as a DER-encoded SET OF ANY structure, as -// described in |i2d_SAMPLE|. +// i2d_ASN1_SET_ANY marshals `in` as a DER-encoded SET OF ANY structure, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ASN1_SET_ANY(const ASN1_SEQUENCE_ANY *in, uint8_t **outp); @@ -1571,25 +1571,25 @@ // functions may be used for debugging and logging. However, the output should // not be consumed programmatically. They may be ambiguous or lose information. -// ASN1_UTCTIME_print writes a human-readable representation of |a| to |out|. It +// ASN1_UTCTIME_print writes a human-readable representation of `a` to `out`. It // returns one on success and zero on error. OPENSSL_EXPORT int ASN1_UTCTIME_print(BIO *out, const ASN1_UTCTIME *a); -// ASN1_GENERALIZEDTIME_print writes a human-readable representation of |a| to -// |out|. It returns one on success and zero on error. +// ASN1_GENERALIZEDTIME_print writes a human-readable representation of `a` to +// `out`. It returns one on success and zero on error. OPENSSL_EXPORT int ASN1_GENERALIZEDTIME_print(BIO *out, const ASN1_GENERALIZEDTIME *a); -// ASN1_TIME_print writes a human-readable representation of |a| to |out|. It +// ASN1_TIME_print writes a human-readable representation of `a` to `out`. It // returns one on success and zero on error. OPENSSL_EXPORT int ASN1_TIME_print(BIO *out, const ASN1_TIME *a); -// ASN1_STRING_print writes a human-readable representation of |str| to |out|. +// ASN1_STRING_print writes a human-readable representation of `str` to `out`. // It returns one on success and zero on error. Unprintable characters are // replaced with '.'. OPENSSL_EXPORT int ASN1_STRING_print(BIO *out, const ASN1_STRING *str); -// The following flags must not collide with |XN_FLAG_*|. +// The following flags must not collide with `XN_FLAG_*`. // ASN1_STRFLGS_ESC_2253 causes characters to be escaped as in RFC 2253, section // 2.4. @@ -1610,12 +1610,12 @@ // byte in the UTF-8 encoding treated as an individual character for purposes of // escape sequences. If not set, each Unicode codepoint in the string is treated // as a character, with wide characters escaped as "\Uxxxx" or "\Wxxxxxxxx". -// Note this can be ambiguous if |ASN1_STRFLGS_ESC_*| are all unset. In that +// Note this can be ambiguous if `ASN1_STRFLGS_ESC_*` are all unset. In that // case, backslashes are not escaped, but wide characters are. #define ASN1_STRFLGS_UTF8_CONVERT 0x10ul // ASN1_STRFLGS_IGNORE_TYPE causes the string type to be ignored. The -// |ASN1_STRING| in-memory representation will be printed directly. +// `ASN1_STRING` in-memory representation will be printed directly. #define ASN1_STRFLGS_IGNORE_TYPE 0x20ul // ASN1_STRFLGS_SHOW_TYPE causes the string type to be included in the output. @@ -1625,15 +1625,15 @@ // RFC 2253 hexstring notation, such as "#0123456789ABCDEF". #define ASN1_STRFLGS_DUMP_ALL 0x80ul -// ASN1_STRFLGS_DUMP_UNKNOWN behaves like |ASN1_STRFLGS_DUMP_ALL| but only +// ASN1_STRFLGS_DUMP_UNKNOWN behaves like `ASN1_STRFLGS_DUMP_ALL` but only // applies to values of unknown type. If unset, unknown values will print // their contents as single-byte characters with escape sequences. #define ASN1_STRFLGS_DUMP_UNKNOWN 0x100ul // ASN1_STRFLGS_DUMP_DER causes hexdumped strings (as determined by -// |ASN1_STRFLGS_DUMP_ALL| or |ASN1_STRFLGS_DUMP_UNKNOWN|) to print the entire +// `ASN1_STRFLGS_DUMP_ALL` or `ASN1_STRFLGS_DUMP_UNKNOWN`) to print the entire // DER element as in RFC 2253, rather than only the contents of the -// |ASN1_STRING|. +// `ASN1_STRING`. #define ASN1_STRFLGS_DUMP_DER 0x200ul // ASN1_STRFLGS_RFC2253 causes the string to be escaped as in RFC 2253, @@ -1643,103 +1643,103 @@ ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN | \ ASN1_STRFLGS_DUMP_DER) -// ASN1_STRING_print_ex writes a human-readable representation of |str| to -// |out|. It returns the number of bytes written on success and -1 on error. If -// |out| is NULL, it returns the number of bytes it would have written, without +// ASN1_STRING_print_ex writes a human-readable representation of `str` to +// `out`. It returns the number of bytes written on success and -1 on error. If +// `out` is NULL, it returns the number of bytes it would have written, without // writing anything. // -// The |flags| should be a combination of combination of |ASN1_STRFLGS_*| +// The `flags` should be a combination of combination of `ASN1_STRFLGS_*` // constants. See the documentation for each flag for how it controls the -// output. If unsure, use |ASN1_STRFLGS_RFC2253|. +// output. If unsure, use `ASN1_STRFLGS_RFC2253`. OPENSSL_EXPORT int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags); -// ASN1_STRING_print_ex_fp behaves like |ASN1_STRING_print_ex| but writes to a -// |FILE| rather than a |BIO|. +// ASN1_STRING_print_ex_fp behaves like `ASN1_STRING_print_ex` but writes to a +// `FILE` rather than a `BIO`. OPENSSL_EXPORT int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags); -// i2a_ASN1_INTEGER writes a human-readable representation of |a| to |bp|. It +// i2a_ASN1_INTEGER writes a human-readable representation of `a` to `bp`. It // returns the number of bytes written on success, or a negative number on -// error. On error, this function may have written a partial output to |bp|. +// error. On error, this function may have written a partial output to `bp`. OPENSSL_EXPORT int i2a_ASN1_INTEGER(BIO *bp, const ASN1_INTEGER *a); -// i2a_ASN1_ENUMERATED writes a human-readable representation of |a| to |bp|. It +// i2a_ASN1_ENUMERATED writes a human-readable representation of `a` to `bp`. It // returns the number of bytes written on success, or a negative number on -// error. On error, this function may have written a partial output to |bp|. +// error. On error, this function may have written a partial output to `bp`. OPENSSL_EXPORT int i2a_ASN1_ENUMERATED(BIO *bp, const ASN1_ENUMERATED *a); -// i2a_ASN1_OBJECT writes a human-readable representation of |a| to |bp|. It +// i2a_ASN1_OBJECT writes a human-readable representation of `a` to `bp`. It // returns the number of bytes written on success, or a negative number on -// error. On error, this function may have written a partial output to |bp|. +// error. On error, this function may have written a partial output to `bp`. OPENSSL_EXPORT int i2a_ASN1_OBJECT(BIO *bp, const ASN1_OBJECT *a); -// i2a_ASN1_STRING writes a text representation of |a|'s contents to |bp|. It +// i2a_ASN1_STRING writes a text representation of `a`'s contents to `bp`. It // returns the number of bytes written on success, or a negative number on -// error. On error, this function may have written a partial output to |bp|. -// |type| is ignored. +// error. On error, this function may have written a partial output to `bp`. +// `type` is ignored. // -// This function does not decode |a| into a Unicode string. It only hex-encodes -// the internal representation of |a|. This is suitable for printing an OCTET +// This function does not decode `a` into a Unicode string. It only hex-encodes +// the internal representation of `a`. This is suitable for printing an OCTET // STRING, but may not be human-readable for any other string type. OPENSSL_EXPORT int i2a_ASN1_STRING(BIO *bp, const ASN1_STRING *a, int type); -// i2t_ASN1_OBJECT calls |OBJ_obj2txt| with |always_return_oid| set to zero. +// i2t_ASN1_OBJECT calls `OBJ_obj2txt` with `always_return_oid` set to zero. OPENSSL_EXPORT int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a); // Low-level encoding functions. -// ASN1_get_object parses a BER element from up to |max_len| bytes at |*inp|. It -// returns |V_ASN1_CONSTRUCTED| if it successfully parsed a constructed element, +// ASN1_get_object parses a BER element from up to `max_len` bytes at `*inp`. It +// returns `V_ASN1_CONSTRUCTED` if it successfully parsed a constructed element, // zero if it successfully parsed a primitive element, and 0x80 on error. On -// success, it additionally advances |*inp| to the element body, sets -// |*out_length|, |*out_tag|, and |*out_class| to the element's length, tag +// success, it additionally advances `*inp` to the element body, sets +// `*out_length`, `*out_tag`, and `*out_class` to the element's length, tag // number, and tag class, respectively, // // Unlike OpenSSL, this function only supports DER. Indefinite and non-minimal // lengths are rejected. // -// This function is difficult to use correctly. Use |CBS_get_asn1| and related +// This function is difficult to use correctly. Use `CBS_get_asn1` and related // functions from bytestring.h. OPENSSL_EXPORT int ASN1_get_object(const unsigned char **inp, long *out_length, int *out_tag, int *out_class, long max_len); -// ASN1_put_object writes the header for a DER or BER element to |*outp| and -// advances |*outp| by the number of bytes written. The caller is responsible -// for ensuring |*outp| has enough space for the output. The header describes an -// element with length |length|, tag number |tag|, and class |xclass|. |xclass| -// should be one of the |V_ASN1_*| tag class constants. The element is primitive -// if |constructed| is zero and constructed if it is one or two. If -// |constructed| is two, |length| is ignored and the element uses +// ASN1_put_object writes the header for a DER or BER element to `*outp` and +// advances `*outp` by the number of bytes written. The caller is responsible +// for ensuring `*outp` has enough space for the output. The header describes an +// element with length `length`, tag number `tag`, and class `xclass`. `xclass` +// should be one of the `V_ASN1_*` tag class constants. The element is primitive +// if `constructed` is zero and constructed if it is one or two. If +// `constructed` is two, `length` is ignored and the element uses // indefinite-length encoding. // -// Use |CBB_add_asn1| instead. +// Use `CBB_add_asn1` instead. OPENSSL_EXPORT void ASN1_put_object(unsigned char **outp, int constructed, int length, int tag, int xclass); -// ASN1_put_eoc writes two zero bytes to |*outp|, advances |*outp| to point past +// ASN1_put_eoc writes two zero bytes to `*outp`, advances `*outp` to point past // those bytes, and returns two. // // Use definite-length encoding instead. OPENSSL_EXPORT int ASN1_put_eoc(unsigned char **outp); // ASN1_object_size returns the number of bytes needed to encode a DER or BER -// value with length |length| and tag number |tag|, or -1 on error. |tag| should -// not include the constructed bit or tag class. If |constructed| is zero or +// value with length `length` and tag number `tag`, or -1 on error. `tag` should +// not include the constructed bit or tag class. If `constructed` is zero or // one, the result uses a definite-length encoding with minimally-encoded -// length, as in DER. If |constructed| is two, the result uses BER +// length, as in DER. If `constructed` is two, the result uses BER // indefinite-length encoding. // -// Use |CBB_add_asn1| instead. +// Use `CBB_add_asn1` instead. OPENSSL_EXPORT int ASN1_object_size(int constructed, int length, int tag); // Function declaration macros. // // The following macros declare functions for ASN.1 types. Prefer writing the -// prototypes directly. Particularly when |type|, |itname|, or |name| differ, +// prototypes directly. Particularly when `type`, `itname`, or `name` differ, // the macros can be difficult to understand. #define DECLARE_ASN1_FUNCTIONS(type) DECLARE_ASN1_FUNCTIONS_name(type, type) @@ -1782,21 +1782,21 @@ // lacked this flag, it enabled an implicit truncation behavior. This has since // been removed. // -// TODO(crbug.com/443769299): Remove this when |ASN1_STRING| is opaque. For now, -// we continue to set it in various codepaths, in case code is querying |flags| +// TODO(crbug.com/443769299): Remove this when `ASN1_STRING` is opaque. For now, +// we continue to set it in various codepaths, in case code is querying `flags` // manually, even though it does nothing. #define ASN1_STRING_FLAG_BITS_LEFT 0x08 -// ASN1_BIT_STRING_num_bytes computes the length of |str| in bytes. If |str|'s -// bit length is a multiple of 8, it sets |*out| to the byte length and returns +// ASN1_BIT_STRING_num_bytes computes the length of `str` in bytes. If `str`'s +// bit length is a multiple of 8, it sets `*out` to the byte length and returns // one. Otherwise, it returns zero. // -// This function may be used with |ASN1_STRING_get0_data| to interpret |str| as +// This function may be used with `ASN1_STRING_get0_data` to interpret `str` as // a byte string. // // This function is no longer necessary. The byte length is always equal to -// |ASN1_STRING_length| and callers can check for a whole number of bytes by -// checking if |ASN1_BIT_STRING_unused_bits| is zero. +// `ASN1_STRING_length` and callers can check for a whole number of bytes by +// checking if `ASN1_BIT_STRING_unused_bits` is zero. OPENSSL_EXPORT int ASN1_BIT_STRING_num_bytes(const ASN1_BIT_STRING *str, size_t *out); @@ -1806,13 +1806,13 @@ // ASN1_STRING_set_default_mask_asc returns one. OPENSSL_EXPORT int ASN1_STRING_set_default_mask_asc(const char *p); -// ASN1_STRING_get_default_mask returns |B_ASN1_UTF8STRING|. +// ASN1_STRING_get_default_mask returns `B_ASN1_UTF8STRING`. OPENSSL_EXPORT unsigned long ASN1_STRING_get_default_mask(void); // ASN1_STRING_TABLE_cleanup does nothing. OPENSSL_EXPORT void ASN1_STRING_TABLE_cleanup(void); -// M_ASN1_* are legacy aliases for various |ASN1_STRING| functions. Use the +// M_ASN1_* are legacy aliases for various `ASN1_STRING` functions. Use the // functions themselves. #define M_ASN1_STRING_length(x) ASN1_STRING_length(x) #define M_ASN1_STRING_type(x) ASN1_STRING_type(x) @@ -1860,30 +1860,30 @@ #define M_ASN1_UTF8STRING_new() ASN1_UTF8STRING_new() #define M_ASN1_UTF8STRING_free(a) ASN1_UTF8STRING_free(a) -// ASN1_INTEGER_set sets |a| to an INTEGER with value |v|. It returns one on +// ASN1_INTEGER_set sets `a` to an INTEGER with value `v`. It returns one on // success and zero on error. // -// Use |ASN1_INTEGER_set_uint64| and |ASN1_INTEGER_set_int64| instead. +// Use `ASN1_INTEGER_set_uint64` and `ASN1_INTEGER_set_int64` instead. OPENSSL_EXPORT int ASN1_INTEGER_set(ASN1_INTEGER *a, long v); -// ASN1_ENUMERATED_set sets |a| to an ENUMERATED with value |v|. It returns one +// ASN1_ENUMERATED_set sets `a` to an ENUMERATED with value `v`. It returns one // on success and zero on error. // -// Use |ASN1_ENUMERATED_set_uint64| and |ASN1_ENUMERATED_set_int64| instead. +// Use `ASN1_ENUMERATED_set_uint64` and `ASN1_ENUMERATED_set_int64` instead. OPENSSL_EXPORT int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v); -// ASN1_INTEGER_get returns the value of |a| as a |long|, or -1 if |a| is out of +// ASN1_INTEGER_get returns the value of `a` as a `long`, or -1 if `a` is out of // range or the wrong type. // // WARNING: This function's return value cannot distinguish errors from -1. -// Use |ASN1_INTEGER_get_uint64| and |ASN1_INTEGER_get_int64| instead. +// Use `ASN1_INTEGER_get_uint64` and `ASN1_INTEGER_get_int64` instead. OPENSSL_EXPORT long ASN1_INTEGER_get(const ASN1_INTEGER *a); -// ASN1_ENUMERATED_get returns the value of |a| as a |long|, or -1 if |a| is out +// ASN1_ENUMERATED_get returns the value of `a` as a `long`, or -1 if `a` is out // of range or the wrong type. // // WARNING: This function's return value cannot distinguish errors from -1. -// Use |ASN1_ENUMERATED_get_uint64| and |ASN1_ENUMERATED_get_int64| instead. +// Use `ASN1_ENUMERATED_get_uint64` and `ASN1_ENUMERATED_get_int64` instead. OPENSSL_EXPORT long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
diff --git a/include/openssl/asn1t.h b/include/openssl/asn1t.h index 22b1688..b89adb8 100644 --- a/include/openssl/asn1t.h +++ b/include/openssl/asn1t.h
@@ -26,8 +26,8 @@ /* 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;
diff --git a/include/openssl/base.h b/include/openssl/base.h index 1ce0e1b..8ded377 100644 --- a/include/openssl/base.h +++ b/include/openssl/base.h
@@ -51,7 +51,7 @@ #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 @@ #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 @@ #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 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)) { \
diff --git a/include/openssl/base64.h b/include/openssl/base64.h index ca265cd..752cb93 100644 --- a/include/openssl/base64.h +++ b/include/openssl/base64.h
@@ -33,29 +33,29 @@ // 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 @@ // 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 @@ // 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 @@ 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 @@ 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];
diff --git a/include/openssl/bio.h b/include/openssl/bio.h index 5c3dda0..d994c11 100644 --- a/include/openssl/bio.h +++ b/include/openssl/bio.h
@@ -37,60 +37,60 @@ DEFINE_STACK_OF(BIO) // BIO_new creates a new BIO with the given method and a reference count of one. -// It returns the fresh |BIO|, or NULL on error. +// It returns the fresh `BIO`, or NULL on error. OPENSSL_EXPORT BIO *BIO_new(const BIO_METHOD *method); -// BIO_free decrements the reference count of |bio|. If the reference count +// BIO_free decrements the reference count of `bio`. If the reference count // drops to zero, it calls the destroy callback, if present, on the method and -// frees |bio| itself. If |bio| is part of a chain (see |BIO_push|), this will -// also free the next |BIO| in the chain, and so on. +// frees `bio` itself. If `bio` is part of a chain (see `BIO_push`), this will +// also free the next `BIO` in the chain, and so on. // -// It returns one if |bio| was NULL or freed. It returns zero if |bio| was +// It returns one if `bio` was NULL or freed. It returns zero if `bio` was // shared and some other owner still owns a reference count to it. // // WARNING: Do not use the return value. Returning zero is not a sign of an -// error, nor an indication to retry the operation. |BIO| is a reference-counted -// type. A given |BIO| object may be shared between multiple parts of an +// error, nor an indication to retry the operation. `BIO` is a reference-counted +// type. A given `BIO` object may be shared between multiple parts of an // application. To correctly track the reference count, without leaks or // use-after-free, each part of the application must release only the reference // counts it owns. OPENSSL_EXPORT int BIO_free(BIO *bio); -// BIO_vfree performs the same actions as |BIO_free|, but has a void return +// BIO_vfree performs the same actions as `BIO_free`, but has a void return // value. This is provided for API-compat. // // TODO(fork): remove. OPENSSL_EXPORT void BIO_vfree(BIO *bio); -// BIO_up_ref increments the reference count of |bio| and returns one. +// BIO_up_ref increments the reference count of `bio` and returns one. OPENSSL_EXPORT int BIO_up_ref(BIO *bio); // Basic I/O. -// BIO_read attempts to read |len| bytes into |data|. It returns the number of +// BIO_read attempts to read `len` bytes into `data`. It returns the number of // bytes read, zero on EOF, or a negative number on error. OPENSSL_EXPORT int BIO_read(BIO *bio, void *data, int len); -// BIO_gets reads a line from |bio| and writes at most |size| bytes into |buf|. +// BIO_gets reads a line from `bio` and writes at most `size` bytes into `buf`. // It returns the number of bytes read or a negative number on error. This // function's output always includes a trailing NUL byte, so it will read at -// most |size - 1| bytes. +// most `size - 1` bytes. // // If the function read a complete line, the output will include the newline -// character, '\n'. If no newline was found before |size - 1| bytes or EOF, it +// character, '\n'. If no newline was found before `size - 1` bytes or EOF, it // outputs the bytes which were available. OPENSSL_EXPORT int BIO_gets(BIO *bio, char *buf, int size); -// BIO_write writes |len| bytes from |data| to |bio|. It returns the number of +// BIO_write writes `len` bytes from `data` to `bio`. It returns the number of // bytes written or a negative number on error. OPENSSL_EXPORT int BIO_write(BIO *bio, const void *data, int len); -// BIO_write_all writes |len| bytes from |data| to |bio|, looping as necessary. +// BIO_write_all writes `len` bytes from `data` to `bio`, looping as necessary. // It returns one if all bytes were successfully written and zero on error. OPENSSL_EXPORT int BIO_write_all(BIO *bio, const void *data, size_t len); -// BIO_puts writes a NUL terminated string from |buf| to |bio|. It returns the +// BIO_puts writes a NUL terminated string from `buf` to `bio`. It returns the // number of bytes written or a negative number on error. OPENSSL_EXPORT int BIO_puts(BIO *bio, const char *buf); @@ -102,23 +102,23 @@ // Low-level control functions. // // These are generic functions for sending control requests to a BIO. In -// general one should use the wrapper functions like |BIO_get_close|. +// general one should use the wrapper functions like `BIO_get_close`. -// BIO_ctrl sends the control request |cmd| to |bio|. The |cmd| argument should -// be one of the |BIO_C_*| values. +// BIO_ctrl sends the control request `cmd` to `bio`. The `cmd` argument should +// be one of the `BIO_C_*` values. OPENSSL_EXPORT long BIO_ctrl(BIO *bio, int cmd, long larg, void *parg); -// BIO_ptr_ctrl acts like |BIO_ctrl| but passes the address of a |void*| -// pointer as |parg| and returns the value that is written to it, or NULL if +// BIO_ptr_ctrl acts like `BIO_ctrl` but passes the address of a `void*` +// pointer as `parg` and returns the value that is written to it, or NULL if // the control request returns <= 0. OPENSSL_EXPORT char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg); -// BIO_int_ctrl acts like |BIO_ctrl| but passes the address of a copy of |iarg| -// as |parg|. +// BIO_int_ctrl acts like `BIO_ctrl` but passes the address of a copy of `iarg` +// as `parg`. OPENSSL_EXPORT long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg); -// BIO_reset resets |bio| to its initial state, the precise meaning of which -// depends on the concrete type of |bio|. It normally returns one on success and +// BIO_reset resets `bio` to its initial state, the precise meaning of which +// depends on the concrete type of `bio`. It normally returns one on success and // <= 0 otherwise. However, for file and fd BIOs, it returns zero on success and // a negative number on error. // @@ -126,29 +126,29 @@ // in this library. OPENSSL_EXPORT int BIO_reset(BIO *bio); -// BIO_eof returns non-zero when |bio| has reached end-of-file. The precise -// meaning of which depends on the concrete type of |bio|. Note that in the +// BIO_eof returns non-zero when `bio` has reached end-of-file. The precise +// meaning of which depends on the concrete type of `bio`. Note that in the // case of BIO_pair this always returns non-zero. OPENSSL_EXPORT int BIO_eof(BIO *bio); -// BIO_set_flags ORs |flags| with |bio->flags|. Unless otherwise documented, -// flags are private to either BoringSSL or the custom |BIO_METHOD|. +// BIO_set_flags ORs `flags` with `bio->flags`. Unless otherwise documented, +// flags are private to either BoringSSL or the custom `BIO_METHOD`. OPENSSL_EXPORT void BIO_set_flags(BIO *bio, int flags); -// BIO_clear_flags ANDs |bio->flags| with the bitwise-complement of |flags|. +// BIO_clear_flags ANDs `bio->flags` with the bitwise-complement of `flags`. // Unless otherwise documented, flags are private to either BoringSSL or the -// custom |BIO_METHOD|. +// custom `BIO_METHOD`. OPENSSL_EXPORT void BIO_clear_flags(BIO *bio, int flags); -// BIO_test_flags returns |bio->flags| AND |flags|. +// BIO_test_flags returns `bio->flags` AND `flags`. OPENSSL_EXPORT int BIO_test_flags(const BIO *bio, int flags); -// BIO_should_read returns non-zero if |bio| encountered a temporary error +// BIO_should_read returns non-zero if `bio` encountered a temporary error // while reading (i.e. EAGAIN), indicating that the caller should retry the // read. OPENSSL_EXPORT int BIO_should_read(const BIO *bio); -// BIO_should_write returns non-zero if |bio| encountered a temporary error +// BIO_should_write returns non-zero if `bio` encountered a temporary error // while writing (i.e. EAGAIN), indicating that the caller should retry the // write. OPENSSL_EXPORT int BIO_should_write(const BIO *bio); @@ -158,10 +158,10 @@ // it was a permanent error and it returns zero. OPENSSL_EXPORT int BIO_should_retry(const BIO *bio); -// BIO_should_io_special returns non-zero if |bio| encountered a temporary +// BIO_should_io_special returns non-zero if `bio` encountered a temporary // error while performing a special I/O operation, indicating that the caller // should retry. The operation that caused the error is returned by -// |BIO_get_retry_reason|. +// `BIO_get_retry_reason`. OPENSSL_EXPORT int BIO_should_io_special(const BIO *bio); // BIO_RR_CONNECT indicates that a connect would have blocked @@ -171,62 +171,62 @@ #define BIO_RR_ACCEPT 0x03 // BIO_get_retry_reason returns the special I/O operation that needs to be -// retried. The return value is one of the |BIO_RR_*| values. +// retried. The return value is one of the `BIO_RR_*` values. OPENSSL_EXPORT int BIO_get_retry_reason(const BIO *bio); // BIO_set_retry_reason sets the special I/O operation that needs to be retried -// to |reason|, which should be one of the |BIO_RR_*| values. +// to `reason`, which should be one of the `BIO_RR_*` values. OPENSSL_EXPORT void BIO_set_retry_reason(BIO *bio, int reason); -// BIO_set_retry_read sets the |BIO_FLAGS_READ| and |BIO_FLAGS_SHOULD_RETRY| -// flags on |bio|. +// BIO_set_retry_read sets the `BIO_FLAGS_READ` and `BIO_FLAGS_SHOULD_RETRY` +// flags on `bio`. OPENSSL_EXPORT void BIO_set_retry_read(BIO *bio); -// BIO_set_retry_write sets the |BIO_FLAGS_WRITE| and |BIO_FLAGS_SHOULD_RETRY| -// flags on |bio|. +// BIO_set_retry_write sets the `BIO_FLAGS_WRITE` and `BIO_FLAGS_SHOULD_RETRY` +// flags on `bio`. OPENSSL_EXPORT void BIO_set_retry_write(BIO *bio); -// BIO_get_retry_flags gets the |BIO_FLAGS_READ|, |BIO_FLAGS_WRITE|, -// |BIO_FLAGS_IO_SPECIAL| and |BIO_FLAGS_SHOULD_RETRY| flags from |bio|. +// BIO_get_retry_flags gets the `BIO_FLAGS_READ`, `BIO_FLAGS_WRITE`, +// `BIO_FLAGS_IO_SPECIAL` and `BIO_FLAGS_SHOULD_RETRY` flags from `bio`. OPENSSL_EXPORT int BIO_get_retry_flags(BIO *bio); -// BIO_clear_retry_flags clears the |BIO_FLAGS_READ|, |BIO_FLAGS_WRITE|, -// |BIO_FLAGS_IO_SPECIAL| and |BIO_FLAGS_SHOULD_RETRY| flags from |bio|. +// BIO_clear_retry_flags clears the `BIO_FLAGS_READ`, `BIO_FLAGS_WRITE`, +// `BIO_FLAGS_IO_SPECIAL` and `BIO_FLAGS_SHOULD_RETRY` flags from `bio`. OPENSSL_EXPORT void BIO_clear_retry_flags(BIO *bio); -// BIO_method_type returns the type of |bio|, which is one of the |BIO_TYPE_*| +// BIO_method_type returns the type of `bio`, which is one of the `BIO_TYPE_*` // values. OPENSSL_EXPORT int BIO_method_type(const BIO *bio); typedef int BIO_info_cb(BIO *, int, int); -// BIO_callback_ctrl allows the callback function to be manipulated. The |cmd| -// arg will generally be |BIO_CTRL_SET_CALLBACK| but arbitrary command values -// can be interpreted by the |BIO|. +// BIO_callback_ctrl allows the callback function to be manipulated. The `cmd` +// arg will generally be `BIO_CTRL_SET_CALLBACK` but arbitrary command values +// can be interpreted by the `BIO`. OPENSSL_EXPORT long BIO_callback_ctrl(BIO *bio, int cmd, BIO_info_cb *fp); // BIO_pending returns the number of bytes pending to be read. OPENSSL_EXPORT size_t BIO_pending(const BIO *bio); -// BIO_ctrl_pending calls |BIO_pending| and exists only for compatibility with +// BIO_ctrl_pending calls `BIO_pending` and exists only for compatibility with // OpenSSL. OPENSSL_EXPORT size_t BIO_ctrl_pending(const BIO *bio); // BIO_wpending returns the number of bytes pending to be written. OPENSSL_EXPORT size_t BIO_wpending(const BIO *bio); -// BIO_set_close sets the close flag for |bio|. The meaning of which depends on -// the type of |bio| but, for example, a memory BIO interprets the close flag +// BIO_set_close sets the close flag for `bio`. The meaning of which depends on +// the type of `bio` but, for example, a memory BIO interprets the close flag // as meaning that it owns its buffer. It returns one on success and zero // otherwise. OPENSSL_EXPORT int BIO_set_close(BIO *bio, int close_flag); // BIO_number_read returns the number of bytes that have been read from -// |bio|. +// `bio`. OPENSSL_EXPORT uint64_t BIO_number_read(const BIO *bio); // BIO_number_written returns the number of bytes that have been written to -// |bio|. +// `bio`. OPENSSL_EXPORT uint64_t BIO_number_written(const BIO *bio); @@ -236,41 +236,41 @@ // the next etc. The most common case is a buffering BIO, which accepts and // buffers writes until flushed into the next BIO in the chain. -// BIO_push adds |appended_bio| to the end of the chain with |bio| at the head. -// It returns |bio|. Note that |appended_bio| may be the head of a chain itself +// BIO_push adds `appended_bio` to the end of the chain with `bio` at the head. +// It returns `bio`. Note that `appended_bio` may be the head of a chain itself // and thus this function can be used to join two chains. // -// BIO_push takes ownership of the caller's reference to |appended_bio|. +// BIO_push takes ownership of the caller's reference to `appended_bio`. OPENSSL_EXPORT BIO *BIO_push(BIO *bio, BIO *appended_bio); -// BIO_pop removes |bio| from the head of a chain and returns the next BIO in +// BIO_pop removes `bio` from the head of a chain and returns the next BIO in // the chain, or NULL if there is no next BIO. // -// The caller takes ownership of the chain's reference to |bio|. +// The caller takes ownership of the chain's reference to `bio`. OPENSSL_EXPORT BIO *BIO_pop(BIO *bio); -// BIO_next returns the next BIO in the chain after |bio|, or NULL if there is +// BIO_next returns the next BIO in the chain after `bio`, or NULL if there is // no such BIO. OPENSSL_EXPORT BIO *BIO_next(BIO *bio); // BIO_find_type walks a chain of BIOs and returns the first that matches -// |type|, which is one of the |BIO_TYPE_*| values. +// `type`, which is one of the `BIO_TYPE_*` values. // -// If |type & 0xff| is non-zero, i.e. |type| is a complete type and contains an -// "index" component, the function looks for an exact match. If |type & 0xff| is -// zero, i.e. |type| just specifies |BIO_TYPE_DESCRIPTOR|, |BIO_TYPE_FILTER|, -// and |BIO_TYPE_SOURCE_SINK| bits, the function looks for any BIO whose type +// If `type & 0xff` is non-zero, i.e. `type` is a complete type and contains an +// "index" component, the function looks for an exact match. If `type & 0xff` is +// zero, i.e. `type` just specifies `BIO_TYPE_DESCRIPTOR`, `BIO_TYPE_FILTER`, +// and `BIO_TYPE_SOURCE_SINK` bits, the function looks for any BIO whose type // contains at least one of those bits. OPENSSL_EXPORT BIO *BIO_find_type(BIO *bio, int type); -// BIO_copy_next_retry sets the retry flags and |retry_reason| of |bio| from +// BIO_copy_next_retry sets the retry flags and `retry_reason` of `bio` from // the next BIO in the chain. OPENSSL_EXPORT void BIO_copy_next_retry(BIO *bio); // Printf functions. -// BIO_printf behaves like |printf| but outputs to |bio| rather than a |FILE|. +// BIO_printf behaves like `printf` but outputs to `bio` rather than a `FILE`. // It returns the number of bytes written or a negative number on error. OPENSSL_EXPORT int BIO_printf(BIO *bio, const char *format, ...) OPENSSL_PRINTF_FORMAT_FUNC(2, 3); @@ -278,98 +278,98 @@ // Utility functions. -// BIO_indent prints min(|indent|, |max_indent|) spaces. It returns one on +// BIO_indent prints min(`indent`, `max_indent`) spaces. It returns one on // success and zero otherwise. OPENSSL_EXPORT int BIO_indent(BIO *bio, unsigned indent, unsigned max_indent); -// BIO_hexdump writes a hex dump of |data| to |bio|. Each line will be indented -// by |indent| spaces. It returns one on success and zero otherwise. +// BIO_hexdump writes a hex dump of `data` to `bio`. Each line will be indented +// by `indent` spaces. It returns one on success and zero otherwise. OPENSSL_EXPORT int BIO_hexdump(BIO *bio, const uint8_t *data, size_t len, unsigned indent); -// ERR_print_errors prints the current contents of the error stack to |bio| +// ERR_print_errors prints the current contents of the error stack to `bio` // using human readable strings where possible. OPENSSL_EXPORT void ERR_print_errors(BIO *bio); -// BIO_read_asn1 reads a single ASN.1 object from |bio|. If successful it sets -// |*out| to be an allocated buffer (that should be freed with |OPENSSL_free|), -// |*out_size| to the length, in bytes, of that buffer and returns one. +// BIO_read_asn1 reads a single ASN.1 object from `bio`. If successful it sets +// `*out` to be an allocated buffer (that should be freed with `OPENSSL_free`), +// `*out_size` to the length, in bytes, of that buffer and returns one. // Otherwise it returns zero. // -// If the length of the object is greater than |max_len| or 2^32 then the +// If the length of the object is greater than `max_len` or 2^32 then the // function will fail. Long-form tags are not supported. If the length of the -// object is indefinite the full contents of |bio| are read, unless it would be -// greater than |max_len|, in which case the function fails. +// object is indefinite the full contents of `bio` are read, unless it would be +// greater than `max_len`, in which case the function fails. // // If the function fails then some unknown amount of data may have been read -// from |bio|. +// from `bio`. OPENSSL_EXPORT int BIO_read_asn1(BIO *bio, uint8_t **out, size_t *out_len, size_t max_len); // Memory BIOs. // -// Memory BIOs can be used as a read-only source (with |BIO_new_mem_buf|) or a -// writable sink (with |BIO_new|, |BIO_s_mem| and |BIO_mem_contents|). Data +// Memory BIOs can be used as a read-only source (with `BIO_new_mem_buf`) or a +// writable sink (with `BIO_new`, `BIO_s_mem` and `BIO_mem_contents`). Data // written to a writable, memory BIO can be recalled by reading from it. // -// Calling |BIO_reset| on a read-only BIO resets it to the original contents. +// Calling `BIO_reset` on a read-only BIO resets it to the original contents. // On a writable BIO, it clears any data. // -// If the close flag is set to |BIO_NOCLOSE| (not the default) then the -// underlying |BUF_MEM| will not be freed when the |BIO| is freed. +// If the close flag is set to `BIO_NOCLOSE` (not the default) then the +// underlying `BUF_MEM` will not be freed when the `BIO` is freed. // -// Memory BIOs support |BIO_gets| and |BIO_puts|. +// Memory BIOs support `BIO_gets` and `BIO_puts`. // -// |BIO_ctrl_pending| returns the number of bytes currently stored. +// `BIO_ctrl_pending` returns the number of bytes currently stored. -// BIO_NOCLOSE and |BIO_CLOSE| can be used as symbolic arguments when a "close +// BIO_NOCLOSE and `BIO_CLOSE` can be used as symbolic arguments when a "close // flag" is passed to a BIO function. #define BIO_NOCLOSE 0 #define BIO_CLOSE 1 -// BIO_s_mem returns a |BIO_METHOD| that uses a in-memory buffer. +// BIO_s_mem returns a `BIO_METHOD` that uses a in-memory buffer. OPENSSL_EXPORT const BIO_METHOD *BIO_s_mem(void); -// BIO_new_mem_buf creates read-only BIO that reads from |len| bytes at |buf|. +// BIO_new_mem_buf creates read-only BIO that reads from `len` bytes at `buf`. // It returns the BIO or NULL on error. This function does not copy or take -// ownership of |buf|. The caller must ensure the memory pointed to by |buf| -// outlives the |BIO|. +// ownership of `buf`. The caller must ensure the memory pointed to by `buf` +// outlives the `BIO`. // -// If |len| is negative, then |buf| is treated as a NUL-terminated string, but +// If `len` is negative, then `buf` is treated as a NUL-terminated string, but // don't depend on this in new code. OPENSSL_EXPORT BIO *BIO_new_mem_buf(const void *buf, ossl_ssize_t len); -// BIO_mem_contents sets |*out_contents| to point to the current contents of -// |bio| and |*out_len| to contain the length of that data. It returns one on +// BIO_mem_contents sets `*out_contents` to point to the current contents of +// `bio` and `*out_len` to contain the length of that data. It returns one on // success and zero otherwise. OPENSSL_EXPORT int BIO_mem_contents(const BIO *bio, const uint8_t **out_contents, size_t *out_len); -// BIO_get_mem_data sets |*contents| to point to the current contents of |bio| +// BIO_get_mem_data sets `*contents` to point to the current contents of `bio` // and returns the length of the data. // -// WARNING: don't use this, use |BIO_mem_contents|. A return value of zero from +// WARNING: don't use this, use `BIO_mem_contents`. A return value of zero from // this function can mean either that it failed or that the memory buffer is // empty. OPENSSL_EXPORT long BIO_get_mem_data(BIO *bio, char **contents); -// BIO_get_mem_ptr sets |*out| to a BUF_MEM containing the current contents of -// |bio|. It returns one on success or zero on error. +// BIO_get_mem_ptr sets `*out` to a BUF_MEM containing the current contents of +// `bio`. It returns one on success or zero on error. OPENSSL_EXPORT int BIO_get_mem_ptr(BIO *bio, BUF_MEM **out); -// BIO_set_mem_buf sets |b| as the contents of |bio|. If |take_ownership| is -// non-zero, then |b| will be freed when |bio| is closed. Returns one on +// BIO_set_mem_buf sets `b` as the contents of `bio`. If `take_ownership` is +// non-zero, then `b` will be freed when `bio` is closed. Returns one on // success or zero otherwise. OPENSSL_EXPORT int BIO_set_mem_buf(BIO *bio, BUF_MEM *b, int take_ownership); // BIO_set_mem_eof_return sets the value that will be returned from reading -// |bio| when empty. If |eof_value| is zero then an empty memory BIO will -// return EOF (that is it will return zero and |BIO_should_retry| will be -// false). If |eof_value| is non zero then it will return |eof_value| when it -// is empty and it will set the read retry flag (that is |BIO_read_retry| is -// true). To avoid ambiguity with a normal positive return value, |eof_value| +// `bio` when empty. If `eof_value` is zero then an empty memory BIO will +// return EOF (that is it will return zero and `BIO_should_retry` will be +// false). If `eof_value` is non zero then it will return `eof_value` when it +// is empty and it will set the read retry flag (that is `BIO_read_retry` is +// true). To avoid ambiguity with a normal positive return value, `eof_value` // should be set to a negative value, typically -1. // // For a read-only BIO, the default is zero (EOF). For a writable BIO, the @@ -379,149 +379,149 @@ // File descriptor BIOs. // -// File descriptor BIOs are wrappers around the system's |read| and |write| -// functions. If the close flag is set then then |close| is called on the +// File descriptor BIOs are wrappers around the system's `read` and `write` +// functions. If the close flag is set then then `close` is called on the // underlying file descriptor when the BIO is freed. // -// |BIO_reset| attempts to seek the file pointer to the start of file using -// |lseek|. +// `BIO_reset` attempts to seek the file pointer to the start of file using +// `lseek`. #if !defined(OPENSSL_NO_POSIX_IO) -// BIO_s_fd returns a |BIO_METHOD| for file descriptor fds. +// BIO_s_fd returns a `BIO_METHOD` for file descriptor fds. OPENSSL_EXPORT const BIO_METHOD *BIO_s_fd(void); -// BIO_new_fd creates a new file descriptor BIO wrapping |fd|. If |close_flag| -// is non-zero, then |fd| will be closed when the BIO is. +// BIO_new_fd creates a new file descriptor BIO wrapping `fd`. If `close_flag` +// is non-zero, then `fd` will be closed when the BIO is. OPENSSL_EXPORT BIO *BIO_new_fd(int fd, int close_flag); #endif -// BIO_set_fd sets the file descriptor of |bio| to |fd|. If |close_flag| is -// non-zero then |fd| will be closed when |bio| is. It returns one on success +// BIO_set_fd sets the file descriptor of `bio` to `fd`. If `close_flag` is +// non-zero then `fd` will be closed when `bio` is. It returns one on success // or zero on error. // -// This function may also be used with socket BIOs (see |BIO_s_socket| and -// |BIO_new_socket|). +// This function may also be used with socket BIOs (see `BIO_s_socket` and +// `BIO_new_socket`). OPENSSL_EXPORT int BIO_set_fd(BIO *bio, int fd, int close_flag); -// BIO_get_fd returns the file descriptor currently in use by |bio| or -1 if -// |bio| does not wrap a file descriptor. If there is a file descriptor and -// |out_fd| is not NULL, it also sets |*out_fd| to the file descriptor. +// BIO_get_fd returns the file descriptor currently in use by `bio` or -1 if +// `bio` does not wrap a file descriptor. If there is a file descriptor and +// `out_fd` is not NULL, it also sets `*out_fd` to the file descriptor. // -// This function may also be used with socket BIOs (see |BIO_s_socket| and -// |BIO_new_socket|). +// This function may also be used with socket BIOs (see `BIO_s_socket` and +// `BIO_new_socket`). OPENSSL_EXPORT int BIO_get_fd(BIO *bio, int *out_fd); // File BIOs. // -// File BIOs are wrappers around a C |FILE| object. +// File BIOs are wrappers around a C `FILE` object. // -// |BIO_flush| on a file BIO calls |fflush| on the wrapped stream. +// `BIO_flush` on a file BIO calls `fflush` on the wrapped stream. // -// |BIO_reset| attempts to seek the file pointer to the start of file using -// |fseek|. +// `BIO_reset` attempts to seek the file pointer to the start of file using +// `fseek`. // -// Setting the close flag causes |fclose| to be called on the stream when the +// Setting the close flag causes `fclose` to be called on the stream when the // BIO is freed. -// BIO_s_file returns a BIO_METHOD that wraps a |FILE|. +// BIO_s_file returns a BIO_METHOD that wraps a `FILE`. OPENSSL_EXPORT const BIO_METHOD *BIO_s_file(void); -// BIO_new_file creates a file BIO by opening |filename| with the given mode. -// See the |fopen| manual page for details of the mode argument. On Windows, -// files may be opened in either binary or text mode so, as in |fopen|, callers -// must specify the desired option in |mode|. +// BIO_new_file creates a file BIO by opening `filename` with the given mode. +// See the `fopen` manual page for details of the mode argument. On Windows, +// files may be opened in either binary or text mode so, as in `fopen`, callers +// must specify the desired option in `mode`. OPENSSL_EXPORT BIO *BIO_new_file(const char *filename, const char *mode); -// BIO_FP_TEXT indicates the |FILE| should be switched to text mode on Windows. +// BIO_FP_TEXT indicates the `FILE` should be switched to text mode on Windows. // It has no effect on non-Windows platforms. #define BIO_FP_TEXT 0x10 -// BIO_new_fp creates a new file BIO that wraps |file|. If |flags| contains -// |BIO_CLOSE|, then |fclose| will be called on |file| when the BIO is closed. +// BIO_new_fp creates a new file BIO that wraps `file`. If `flags` contains +// `BIO_CLOSE`, then `fclose` will be called on `file` when the BIO is closed. // -// On Windows, if |flags| contains |BIO_FP_TEXT|, this function will -// additionally switch |file| to text mode. This is not recommended, but may be -// required for OpenSSL compatibility. If |file| was not already in text mode, -// mode changes can cause unflushed data in |file| to be written in unexpected -// ways. See |_setmode| in Windows documentation for details. +// On Windows, if `flags` contains `BIO_FP_TEXT`, this function will +// additionally switch `file` to text mode. This is not recommended, but may be +// required for OpenSSL compatibility. If `file` was not already in text mode, +// mode changes can cause unflushed data in `file` to be written in unexpected +// ways. See `_setmode` in Windows documentation for details. // -// Unlike OpenSSL, if |flags| does not contain |BIO_FP_TEXT|, the translation -// mode of |file| is left as-is. In OpenSSL, |file| will be set to binary, with +// Unlike OpenSSL, if `flags` does not contain `BIO_FP_TEXT`, the translation +// mode of `file` is left as-is. In OpenSSL, `file` will be set to binary, with // the same pitfalls as above. BoringSSL does not do this so that wrapping a -// |FILE| in a |BIO| will not inadvertently change its state. +// `FILE` in a `BIO` will not inadvertently change its state. // // To avoid these pitfalls, callers should set the desired translation mode when // opening the file. If targeting just BoringSSL, this is sufficient. If -// targeting both OpenSSL and BoringSSL, callers should set |BIO_FP_TEXT| to +// targeting both OpenSSL and BoringSSL, callers should set `BIO_FP_TEXT` to // match the desired state of the file. OPENSSL_EXPORT BIO *BIO_new_fp(FILE *file, int flags); -// BIO_get_fp sets |*out_file| to the current |FILE| for |bio|. It returns one +// BIO_get_fp sets `*out_file` to the current `FILE` for `bio`. It returns one // on success and zero otherwise. OPENSSL_EXPORT int BIO_get_fp(BIO *bio, FILE **out_file); -// BIO_set_fp sets the |FILE| for |bio|. If |flags| contains |BIO_CLOSE| then -// |fclose| will be called on |file| when |bio| is closed. It returns one on +// BIO_set_fp sets the `FILE` for `bio`. If `flags` contains `BIO_CLOSE` then +// `fclose` will be called on `file` when `bio` is closed. It returns one on // success and zero otherwise. // -// On Windows, if |flags| contains |BIO_FP_TEXT|, this function will -// additionally switch |file| to text mode. This is not recommended, but may be -// required for OpenSSL compatibility. If |file| was not already in text mode, -// mode changes can cause unflushed data in |file| to be written in unexpected -// ways. See |_setmode| in Windows documentation for details. +// On Windows, if `flags` contains `BIO_FP_TEXT`, this function will +// additionally switch `file` to text mode. This is not recommended, but may be +// required for OpenSSL compatibility. If `file` was not already in text mode, +// mode changes can cause unflushed data in `file` to be written in unexpected +// ways. See `_setmode` in Windows documentation for details. // -// Unlike OpenSSL, if |flags| does not contain |BIO_FP_TEXT|, the translation -// mode of |file| is left as-is. In OpenSSL, |file| will be set to binary, with +// Unlike OpenSSL, if `flags` does not contain `BIO_FP_TEXT`, the translation +// mode of `file` is left as-is. In OpenSSL, `file` will be set to binary, with // the same pitfalls as above. BoringSSL does not do this so that wrapping a -// |FILE| in a |BIO| will not inadvertently change its state. +// `FILE` in a `BIO` will not inadvertently change its state. // // To avoid these pitfalls, callers should set the desired translation mode when // opening the file. If targeting just BoringSSL, this is sufficient. If -// targeting both OpenSSL and BoringSSL, callers should set |BIO_FP_TEXT| to +// targeting both OpenSSL and BoringSSL, callers should set `BIO_FP_TEXT` to // match the desired state of the file. OPENSSL_EXPORT int BIO_set_fp(BIO *bio, FILE *file, int flags); -// BIO_read_filename opens |filename| for reading and sets the result as the -// |FILE| for |bio|. It returns one on success and zero otherwise. The |FILE| -// will be closed when |bio| is freed. On Windows, the file is opened in binary +// BIO_read_filename opens `filename` for reading and sets the result as the +// `FILE` for `bio`. It returns one on success and zero otherwise. The `FILE` +// will be closed when `bio` is freed. On Windows, the file is opened in binary // mode. OPENSSL_EXPORT int BIO_read_filename(BIO *bio, const char *filename); -// BIO_write_filename opens |filename| for writing and sets the result as the -// |FILE| for |bio|. It returns one on success and zero otherwise. The |FILE| -// will be closed when |bio| is freed. On Windows, the file is opened in binary +// BIO_write_filename opens `filename` for writing and sets the result as the +// `FILE` for `bio`. It returns one on success and zero otherwise. The `FILE` +// will be closed when `bio` is freed. On Windows, the file is opened in binary // mode. OPENSSL_EXPORT int BIO_write_filename(BIO *bio, const char *filename); -// BIO_append_filename opens |filename| for appending and sets the result as -// the |FILE| for |bio|. It returns one on success and zero otherwise. The -// |FILE| will be closed when |bio| is freed. On Windows, the file is opened in +// BIO_append_filename opens `filename` for appending and sets the result as +// the `FILE` for `bio`. It returns one on success and zero otherwise. The +// `FILE` will be closed when `bio` is freed. On Windows, the file is opened in // binary mode. OPENSSL_EXPORT int BIO_append_filename(BIO *bio, const char *filename); -// BIO_rw_filename opens |filename| for reading and writing and sets the result -// as the |FILE| for |bio|. It returns one on success and zero otherwise. The -// |FILE| will be closed when |bio| is freed. On Windows, the file is opened in +// BIO_rw_filename opens `filename` for reading and writing and sets the result +// as the `FILE` for `bio`. It returns one on success and zero otherwise. The +// `FILE` will be closed when `bio` is freed. On Windows, the file is opened in // binary mode. OPENSSL_EXPORT int BIO_rw_filename(BIO *bio, const char *filename); -// BIO_tell returns the file offset of |bio|, or a negative number on error or -// if |bio| does not support the operation. +// BIO_tell returns the file offset of `bio`, or a negative number on error or +// if `bio` does not support the operation. // -// TODO(crbug.com/42290329): On platforms where |long| is 32-bit, this function +// TODO(crbug.com/42290329): On platforms where `long` is 32-bit, this function // cannot report 64-bit offsets. OPENSSL_EXPORT long BIO_tell(BIO *bio); -// BIO_seek sets the file offset of |bio| to |offset|. It returns a non-negative -// number on success and a negative number on error. If |bio| is a file -// descriptor |BIO|, it returns the resulting file offset on success. If |bio| -// is a file |BIO|, it returns zero on success. +// BIO_seek sets the file offset of `bio` to `offset`. It returns a non-negative +// number on success and a negative number on error. If `bio` is a file +// descriptor `BIO`, it returns the resulting file offset on success. If `bio` +// is a file `BIO`, it returns zero on success. // // WARNING: This function's return value conventions differs from most functions // in this library. // -// TODO(crbug.com/42290329): On platforms where |long| is 32-bit, this function +// TODO(crbug.com/42290329): On platforms where `long` is 32-bit, this function // cannot handle 64-bit offsets. OPENSSL_EXPORT long BIO_seek(BIO *bio, long offset); @@ -529,21 +529,21 @@ // Socket BIOs. // // Socket BIOs behave like file descriptor BIOs but, on Windows systems, wrap -// the system's |recv| and |send| functions instead of |read| and |write|. On +// the system's `recv` and `send` functions instead of `read` and `write`. On // Windows, file descriptors are provided by C runtime and are not // interchangeable with sockets. // -// Socket BIOs may be used with |BIO_set_fd| and |BIO_get_fd|. +// Socket BIOs may be used with `BIO_set_fd` and `BIO_get_fd`. // -// TODO(davidben): Add separate APIs and fix the internals to use |SOCKET|s +// TODO(davidben): Add separate APIs and fix the internals to use `SOCKET`s // around rather than rely on int casts. #if !defined(OPENSSL_NO_SOCK) OPENSSL_EXPORT const BIO_METHOD *BIO_s_socket(void); // BIO_new_socket allocates and initialises a fresh BIO which will read and -// write to the socket |fd|. If |close_flag| is |BIO_CLOSE| then closing the -// BIO will close |fd|. It returns the fresh |BIO| or NULL on error. +// write to the socket `fd`. If `close_flag` is `BIO_CLOSE` then closing the +// BIO will close `fd`. It returns the fresh `BIO` or NULL on error. OPENSSL_EXPORT BIO *BIO_new_socket(int fd, int close_flag); #endif // !OPENSSL_NO_SOCK @@ -557,38 +557,38 @@ OPENSSL_EXPORT const BIO_METHOD *BIO_s_connect(void); // BIO_new_connect returns a BIO that connects to the given hostname and port. -// The |host_and_optional_port| argument should be of the form +// The `host_and_optional_port` argument should be of the form // "www.example.com" or "www.example.com:443". If the port is omitted, it must -// be provided with |BIO_set_conn_port|. +// be provided with `BIO_set_conn_port`. // // It returns the new BIO on success, or NULL on error. OPENSSL_EXPORT BIO *BIO_new_connect(const char *host_and_optional_port); -// BIO_set_conn_hostname sets |host_and_optional_port| as the hostname and -// optional port that |bio| will connect to. If the port is omitted, it must be -// provided with |BIO_set_conn_port|. +// BIO_set_conn_hostname sets `host_and_optional_port` as the hostname and +// optional port that `bio` will connect to. If the port is omitted, it must be +// provided with `BIO_set_conn_port`. // // It returns one on success and zero otherwise. OPENSSL_EXPORT int BIO_set_conn_hostname(BIO *bio, const char *host_and_optional_port); -// BIO_set_conn_port sets |port_str| as the port or service name that |bio| +// BIO_set_conn_port sets `port_str` as the port or service name that `bio` // will connect to. It returns one on success and zero otherwise. OPENSSL_EXPORT int BIO_set_conn_port(BIO *bio, const char *port_str); -// BIO_set_conn_int_port sets |*port| as the port that |bio| will connect to. +// BIO_set_conn_int_port sets `*port` as the port that `bio` will connect to. // It returns one on success and zero otherwise. OPENSSL_EXPORT int BIO_set_conn_int_port(BIO *bio, const int *port); -// BIO_set_nbio sets whether |bio| will use non-blocking I/O operations. It +// BIO_set_nbio sets whether `bio` will use non-blocking I/O operations. It // returns one on success and zero otherwise. This only works for connect BIOs -// and must be called before |bio| is connected to take effect. +// and must be called before `bio` is connected to take effect. // // For socket and fd BIOs, callers must configure blocking vs. non-blocking I/O // using the underlying platform APIs. OPENSSL_EXPORT int BIO_set_nbio(BIO *bio, int on); -// BIO_do_connect connects |bio| if it has not been connected yet. It returns +// BIO_do_connect connects `bio` if it has not been connected yet. It returns // one on success and <= 0 otherwise. OPENSSL_EXPORT int BIO_do_connect(BIO *bio); #endif // !OPENSSL_NO_SOCK @@ -607,7 +607,7 @@ the previous write operation. */ // BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT is unsupported as it is unused by consumers -// and depends on |timeval|, which is not 2038-clean on all platforms. +// and depends on `timeval`, which is not 2038-clean on all platforms. #define BIO_CTRL_DGRAM_GET_PEER 46 @@ -619,154 +619,154 @@ // BIO pairs provide a "loopback" like system: a pair of BIOs where data // written to one can be read from the other and vice versa. -// BIO_new_bio_pair sets |*out1| and |*out2| to two freshly created BIOs where +// BIO_new_bio_pair sets `*out1` and `*out2` to two freshly created BIOs where // data written to one can be read from the other and vice versa. The -// |writebuf1| argument gives the size of the buffer used in |*out1| and -// |writebuf2| for |*out2|. It returns one on success and zero on error. +// `writebuf1` argument gives the size of the buffer used in `*out1` and +// `writebuf2` for `*out2`. It returns one on success and zero on error. OPENSSL_EXPORT int BIO_new_bio_pair(BIO **out1, size_t writebuf1, BIO **out2, size_t writebuf2); // BIO_ctrl_get_read_request returns the number of bytes that the other side of -// |bio| tried (unsuccessfully) to read. +// `bio` tried (unsuccessfully) to read. OPENSSL_EXPORT size_t BIO_ctrl_get_read_request(BIO *bio); -// BIO_ctrl_get_write_guarantee returns the number of bytes that |bio| (which -// must have been returned by |BIO_new_bio_pair|) will accept on the next -// |BIO_write| call. +// BIO_ctrl_get_write_guarantee returns the number of bytes that `bio` (which +// must have been returned by `BIO_new_bio_pair`) will accept on the next +// `BIO_write` call. OPENSSL_EXPORT size_t BIO_ctrl_get_write_guarantee(BIO *bio); -// BIO_shutdown_wr marks |bio| as closed, from the point of view of the other -// side of the pair. Future |BIO_write| calls on |bio| will fail. It returns +// BIO_shutdown_wr marks `bio` as closed, from the point of view of the other +// side of the pair. Future `BIO_write` calls on `bio` will fail. It returns // one on success and zero otherwise. OPENSSL_EXPORT int BIO_shutdown_wr(BIO *bio); // Custom BIOs. // -// Consumers can create custom |BIO|s by filling in a |BIO_METHOD| and using +// Consumers can create custom `BIO`s by filling in a `BIO_METHOD` and using // low-level control functions to set state. -// BIO_get_new_index returns a new "type" value for a custom |BIO|, or -1 on +// BIO_get_new_index returns a new "type" value for a custom `BIO`, or -1 on // error. OPENSSL_EXPORT int BIO_get_new_index(void); -// BIO_meth_new returns a newly-allocated |BIO_METHOD| or NULL on allocation -// error. The |type| specifies the type that will be returned by -// |BIO_method_type|. If this is unnecessary, this value may be zero. The |name| +// BIO_meth_new returns a newly-allocated `BIO_METHOD` or NULL on allocation +// error. The `type` specifies the type that will be returned by +// `BIO_method_type`. If this is unnecessary, this value may be zero. The `name` // parameter is vestigial and may be NULL. // -// Use the |BIO_meth_set_*| functions below to initialize the |BIO_METHOD|. The -// function implementations may use |BIO_set_data| and |BIO_get_data| to add -// method-specific state to associated |BIO|s. Additionally, |BIO_set_init| must -// be called after an associated |BIO| is fully initialized. State set via -// |BIO_set_data| may be released by configuring a destructor with -// |BIO_meth_set_destroy|. +// Use the `BIO_meth_set_*` functions below to initialize the `BIO_METHOD`. The +// function implementations may use `BIO_set_data` and `BIO_get_data` to add +// method-specific state to associated `BIO`s. Additionally, `BIO_set_init` must +// be called after an associated `BIO` is fully initialized. State set via +// `BIO_set_data` may be released by configuring a destructor with +// `BIO_meth_set_destroy`. OPENSSL_EXPORT BIO_METHOD *BIO_meth_new(int type, const char *name); -// BIO_meth_free releases memory associated with |method|. +// BIO_meth_free releases memory associated with `method`. OPENSSL_EXPORT void BIO_meth_free(BIO_METHOD *method); -// BIO_meth_set_create sets a function to be called on |BIO_new| for |method| +// BIO_meth_set_create sets a function to be called on `BIO_new` for `method` // and returns one. The function should return one on success and zero on // error. OPENSSL_EXPORT int BIO_meth_set_create(BIO_METHOD *method, int (*create_func)(BIO *)); -// BIO_meth_set_destroy sets a function to release data associated with a |BIO| +// BIO_meth_set_destroy sets a function to release data associated with a `BIO` // and returns one. The function's return value is ignored. // -// As the |BIO| is about to be destroyed, it is not necessary for |destroy_func| -// to clear the BIO's state with |BIO_set_data| or |BIO_set_init|. There is no -// harm in clearing them, but the |BIO| will not be passed to |BIO| operations, -// unless |destroy_func| itself does so. +// As the `BIO` is about to be destroyed, it is not necessary for `destroy_func` +// to clear the BIO's state with `BIO_set_data` or `BIO_set_init`. There is no +// harm in clearing them, but the `BIO` will not be passed to `BIO` operations, +// unless `destroy_func` itself does so. OPENSSL_EXPORT int BIO_meth_set_destroy(BIO_METHOD *method, int (*destroy_func)(BIO *)); -// BIO_meth_set_write sets the implementation of |BIO_write| for |method| and -// returns one. |BIO_METHOD|s which implement |BIO_write| should also implement -// |BIO_CTRL_FLUSH|. (See |BIO_meth_set_ctrl|.) +// BIO_meth_set_write sets the implementation of `BIO_write` for `method` and +// returns one. `BIO_METHOD`s which implement `BIO_write` should also implement +// `BIO_CTRL_FLUSH`. (See `BIO_meth_set_ctrl`.) OPENSSL_EXPORT int BIO_meth_set_write(BIO_METHOD *method, int (*write_func)(BIO *, const char *, int)); -// BIO_meth_set_read sets the implementation of |BIO_read| for |method| and +// BIO_meth_set_read sets the implementation of `BIO_read` for `method` and // returns one. OPENSSL_EXPORT int BIO_meth_set_read(BIO_METHOD *method, int (*read_func)(BIO *, char *, int)); -// BIO_meth_set_gets sets the implementation of |BIO_gets| for |method| and +// BIO_meth_set_gets sets the implementation of `BIO_gets` for `method` and // returns one. OPENSSL_EXPORT int BIO_meth_set_gets(BIO_METHOD *method, int (*gets_func)(BIO *, char *, int)); -// BIO_meth_set_ctrl sets the implementation of |BIO_ctrl| for |method| and +// BIO_meth_set_ctrl sets the implementation of `BIO_ctrl` for `method` and // returns one. OPENSSL_EXPORT int BIO_meth_set_ctrl(BIO_METHOD *method, long (*ctrl_func)(BIO *, int, long, void *)); -// BIO_meth_set_callback_ctrl sets the implementation of |BIO_callback_ctrl| for -// |method| and returns one. +// BIO_meth_set_callback_ctrl sets the implementation of `BIO_callback_ctrl` for +// `method` and returns one. OPENSSL_EXPORT int BIO_meth_set_callback_ctrl( BIO_METHOD *method, long (*callback_ctrl_func)(BIO *, int, BIO_info_cb *)); -// BIO_set_data sets custom data on |bio|. It may be retried with -// |BIO_get_data|. +// BIO_set_data sets custom data on `bio`. It may be retried with +// `BIO_get_data`. // -// This function should only be called by the implementation of a custom |BIO|. -// In particular, the data pointer of a built-in |BIO| is private to the -// library. For other uses, see |BIO_set_ex_data| and |BIO_set_app_data|. +// This function should only be called by the implementation of a custom `BIO`. +// In particular, the data pointer of a built-in `BIO` is private to the +// library. For other uses, see `BIO_set_ex_data` and `BIO_set_app_data`. OPENSSL_EXPORT void BIO_set_data(BIO *bio, void *ptr); -// BIO_get_data returns custom data on |bio| set by |BIO_get_data|. +// BIO_get_data returns custom data on `bio` set by `BIO_get_data`. // -// This function should only be called by the implementation of a custom |BIO|. -// In particular, the data pointer of a built-in |BIO| is private to the -// library. For other uses, see |BIO_get_ex_data| and |BIO_get_app_data|. +// This function should only be called by the implementation of a custom `BIO`. +// In particular, the data pointer of a built-in `BIO` is private to the +// library. For other uses, see `BIO_get_ex_data` and `BIO_get_app_data`. OPENSSL_EXPORT void *BIO_get_data(BIO *bio); -// BIO_set_init sets whether |bio| has been fully initialized. Until fully -// initialized, |BIO_read| and |BIO_write| will fail. +// BIO_set_init sets whether `bio` has been fully initialized. Until fully +// initialized, `BIO_read` and `BIO_write` will fail. OPENSSL_EXPORT void BIO_set_init(BIO *bio, int init); -// BIO_get_init returns whether |bio| has been fully initialized. +// BIO_get_init returns whether `bio` has been fully initialized. OPENSSL_EXPORT int BIO_get_init(BIO *bio); -// These are values of the |cmd| argument to |BIO_ctrl|. +// These are values of the `cmd` argument to `BIO_ctrl`. -// BIO_CTRL_RESET implements |BIO_reset|. The arguments are unused. +// BIO_CTRL_RESET implements `BIO_reset`. The arguments are unused. #define BIO_CTRL_RESET 1 -// BIO_CTRL_EOF implements |BIO_eof|. The arguments are unused. +// BIO_CTRL_EOF implements `BIO_eof`. The arguments are unused. #define BIO_CTRL_EOF 2 // BIO_CTRL_INFO is a legacy command that returns information specific to the -// type of |BIO|. It is not safe to call generically and should not be -// implemented in new |BIO| types. +// type of `BIO`. It is not safe to call generically and should not be +// implemented in new `BIO` types. #define BIO_CTRL_INFO 3 -// BIO_CTRL_GET_CLOSE returns the close flag set by |BIO_CTRL_SET_CLOSE|. The +// BIO_CTRL_GET_CLOSE returns the close flag set by `BIO_CTRL_SET_CLOSE`. The // arguments are unused. #define BIO_CTRL_GET_CLOSE 8 -// BIO_CTRL_SET_CLOSE implements |BIO_set_close|. The |larg| argument is the +// BIO_CTRL_SET_CLOSE implements `BIO_set_close`. The `larg` argument is the // close flag. #define BIO_CTRL_SET_CLOSE 9 -// BIO_CTRL_PENDING implements |BIO_pending|. The arguments are unused. +// BIO_CTRL_PENDING implements `BIO_pending`. The arguments are unused. #define BIO_CTRL_PENDING 10 -// BIO_CTRL_FLUSH implements |BIO_flush|. The arguments are unused. +// BIO_CTRL_FLUSH implements `BIO_flush`. The arguments are unused. #define BIO_CTRL_FLUSH 11 -// BIO_CTRL_WPENDING implements |BIO_wpending|. The arguments are unused. +// BIO_CTRL_WPENDING implements `BIO_wpending`. The arguments are unused. #define BIO_CTRL_WPENDING 13 // BIO_CTRL_SET_CALLBACK sets an informational callback of type // int cb(BIO *bio, int state, int ret) #define BIO_CTRL_SET_CALLBACK 14 -// BIO_CTRL_GET_CALLBACK returns the callback set by |BIO_CTRL_SET_CALLBACK|. +// BIO_CTRL_GET_CALLBACK returns the callback set by `BIO_CTRL_SET_CALLBACK`. #define BIO_CTRL_GET_CALLBACK 15 // The following are never used, but are defined to aid porting existing code. @@ -780,7 +780,7 @@ // ex_data functions. // -// See |ex_data.h| for details. +// See `ex_data.h` for details. OPENSSL_EXPORT int BIO_get_ex_new_index(long argl, void *argp, CRYPTO_EX_unused *unused, @@ -795,19 +795,19 @@ // Deprecated functions. -// BIO_free_all calls |BIO_free|. Code that targets BoringSSL does not need to -// call a separate free function for |BIO|s that are part of a chain. +// BIO_free_all calls `BIO_free`. Code that targets BoringSSL does not need to +// call a separate free function for `BIO`s that are part of a chain. OPENSSL_EXPORT void BIO_free_all(BIO *bio); typedef BIO_info_cb bio_info_cb; -// BIO_f_base64 returns a filter |BIO| that base64-encodes data written into -// it, and decodes data read from it. |BIO_gets| is not supported. Call -// |BIO_flush| when done writing, to signal that no more data are to be -// encoded. The flag |BIO_FLAGS_BASE64_NO_NL| may be set to encode all the data +// BIO_f_base64 returns a filter `BIO` that base64-encodes data written into +// it, and decodes data read from it. `BIO_gets` is not supported. Call +// `BIO_flush` when done writing, to signal that no more data are to be +// encoded. The flag `BIO_FLAGS_BASE64_NO_NL` may be set to encode all the data // on one line. // -// Use |EVP_EncodeBlock| and |EVP_DecodeBase64| instead. +// Use `EVP_EncodeBlock` and `EVP_DecodeBase64` instead. OPENSSL_EXPORT const BIO_METHOD *BIO_f_base64(void); OPENSSL_EXPORT void BIO_set_retry_special(BIO *bio); @@ -815,41 +815,41 @@ // BIO_set_write_buffer_size returns zero. OPENSSL_EXPORT int BIO_set_write_buffer_size(BIO *bio, int buffer_size); -// BIO_set_shutdown sets a method-specific "shutdown" bit on |bio|. +// BIO_set_shutdown sets a method-specific "shutdown" bit on `bio`. OPENSSL_EXPORT void BIO_set_shutdown(BIO *bio, int shutdown); // BIO_get_shutdown returns the method-specific "shutdown" bit. OPENSSL_EXPORT int BIO_get_shutdown(BIO *bio); -// BIO_meth_set_puts returns one. |BIO_puts| is implemented with |BIO_write| in +// BIO_meth_set_puts returns one. `BIO_puts` is implemented with `BIO_write` in // BoringSSL. OPENSSL_EXPORT int BIO_meth_set_puts(BIO_METHOD *method, int (*puts)(BIO *, const char *)); #if !defined(OPENSSL_NO_SOCK) // The following functions return function pointers, possibly NULL, which are -// compatible with the corresponding |BIO_meth_set_*| function. |method| must be -// |BIO_s_socket| or the program will abort. +// compatible with the corresponding `BIO_meth_set_*` function. `method` must be +// `BIO_s_socket` or the program will abort. // // Using these functions is inherently unsafe and fragile. It is not possible to // use them in a future-proof way. See // https://github.com/openssl/openssl/issues/26047 for details. BoringSSL // implements them solely for compatibility with Folly and older versions of // PostgreSQL. To work around the future-proofing problems, the return values -// may diverge from the true implementation of |BIO_s_socket|. +// may diverge from the true implementation of `BIO_s_socket`. // // Caller should not use these functions. They are not necessary to define -// custom |BIO_METHOD|s. Instead, callers should either: +// custom `BIO_METHOD`s. Instead, callers should either: // -// - Define a custom |BIO_METHOD| that owns a socket |BIO| somewhere in the -// custom data. See |BIO_set_data|. +// - Define a custom `BIO_METHOD` that owns a socket `BIO` somewhere in the +// custom data. See `BIO_set_data`. // -// - Define a custom |BIO_METHOD| that wraps a socket |BIO| as a filter. See -// |BIO_push| and |BIO_next|. +// - Define a custom `BIO_METHOD` that wraps a socket `BIO` as a filter. See +// `BIO_push` and `BIO_next`. // -// - Define a custom |BIO_METHOD| without |BIO_s_socket| at all. If not using -// the built-in read or write functions, |BIO_s_socket| only provides a no-op -// |BIO_CTRL_FLUSH| implementation. This can be implemented by the caller. +// - Define a custom `BIO_METHOD` without `BIO_s_socket` at all. If not using +// the built-in read or write functions, `BIO_s_socket` only provides a no-op +// `BIO_CTRL_FLUSH` implementation. This can be implemented by the caller. OPENSSL_EXPORT int (*BIO_meth_get_write(const BIO_METHOD *method))(BIO *, const char *, int); @@ -881,8 +881,8 @@ // or change the data in any way. #define BIO_FLAGS_MEM_RDONLY 0x200 -// BIO_TYPE_DESCRIPTOR denotes that the |BIO| responds to the |BIO_C_SET_FD| -// (|BIO_set_fd|) and |BIO_C_GET_FD| (|BIO_get_fd|) control hooks. +// BIO_TYPE_DESCRIPTOR denotes that the `BIO` responds to the `BIO_C_SET_FD` +// (`BIO_set_fd`) and `BIO_C_GET_FD` (`BIO_get_fd`) control hooks. #define BIO_TYPE_DESCRIPTOR 0x0100 // socket, fd, connect or accept #define BIO_TYPE_FILTER 0x0200 #define BIO_TYPE_SOURCE_SINK 0x0400 @@ -912,7 +912,7 @@ #define BIO_TYPE_ASN1 (22 | BIO_TYPE_FILTER) #define BIO_TYPE_COMP (23 | BIO_TYPE_FILTER) -// BIO_TYPE_START is the first user-allocated |BIO| type. No pre-defined type, +// BIO_TYPE_START is the first user-allocated `BIO` type. No pre-defined type, // flag bits aside, may exceed this value. #define BIO_TYPE_START 128
diff --git a/include/openssl/blake2.h b/include/openssl/blake2.h index 2284591..7511e09 100644 --- a/include/openssl/blake2.h +++ b/include/openssl/blake2.h
@@ -36,22 +36,22 @@ 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]);
diff --git a/include/openssl/bn.h b/include/openssl/bn.h index f0b5334..dbb8376 100644 --- a/include/openssl/bn.h +++ b/include/openssl/bn.h
@@ -43,10 +43,10 @@ // BN_ULONG is the native word size when working with big integers. // // Note: on some platforms, inttypes.h does not define print format macros in -// C++ unless |__STDC_FORMAT_MACROS| defined. This is due to text in C99 which +// C++ unless `__STDC_FORMAT_MACROS` defined. This is due to text in C99 which // was never adopted in any C++ standard and explicitly overruled in C++11. As -// this is a public header, bn.h does not define |__STDC_FORMAT_MACROS| itself. -// Projects which use |BN_*_FMT*| with outdated C headers may need to define it +// this is a public header, bn.h does not define `__STDC_FORMAT_MACROS` itself. +// Projects which use `BN_*_FMT*` with outdated C headers may need to define it // externally. #if defined(OPENSSL_64_BIT) typedef uint64_t BN_ULONG; @@ -70,26 +70,26 @@ // BN_new creates a new, allocated BIGNUM and initialises it. OPENSSL_EXPORT BIGNUM *BN_new(void); -// BN_init initialises a stack allocated |BIGNUM|. +// BN_init initialises a stack allocated `BIGNUM`. OPENSSL_EXPORT void BN_init(BIGNUM *bn); -// BN_free frees the data referenced by |bn| and, if |bn| was originally -// allocated on the heap, frees |bn| also. +// BN_free frees the data referenced by `bn` and, if `bn` was originally +// allocated on the heap, frees `bn` also. OPENSSL_EXPORT void BN_free(BIGNUM *bn); -// BN_clear_free erases and frees the data referenced by |bn| and, if |bn| was -// originally allocated on the heap, frees |bn| also. +// BN_clear_free erases and frees the data referenced by `bn` and, if `bn` was +// originally allocated on the heap, frees `bn` also. OPENSSL_EXPORT void BN_clear_free(BIGNUM *bn); -// BN_dup allocates a new BIGNUM and sets it equal to |src|. It returns the +// BN_dup allocates a new BIGNUM and sets it equal to `src`. It returns the // allocated BIGNUM on success or NULL otherwise. OPENSSL_EXPORT BIGNUM *BN_dup(const BIGNUM *src); -// BN_copy sets |dest| equal to |src| and returns |dest| or NULL on allocation +// BN_copy sets `dest` equal to `src` and returns `dest` or NULL on allocation // failure. OPENSSL_EXPORT BIGNUM *BN_copy(BIGNUM *dest, const BIGNUM *src); -// BN_clear sets |bn| to zero and erases the old data. +// BN_clear sets `bn` to zero and erases the old data. OPENSSL_EXPORT void BN_clear(BIGNUM *bn); // BN_value_one returns a static BIGNUM with value 1. @@ -99,140 +99,140 @@ // Basic functions. // BN_num_bits returns the minimum number of bits needed to represent the -// absolute value of |bn|. +// absolute value of `bn`. OPENSSL_EXPORT unsigned BN_num_bits(const BIGNUM *bn); // BN_num_bytes returns the minimum number of bytes needed to represent the -// absolute value of |bn|. +// absolute value of `bn`. // -// While |size_t| is the preferred type for byte counts, callers can assume that -// |BIGNUM|s are bounded such that this value, and its corresponding bit count, -// will always fit in |int|. +// While `size_t` is the preferred type for byte counts, callers can assume that +// `BIGNUM`s are bounded such that this value, and its corresponding bit count, +// will always fit in `int`. OPENSSL_EXPORT unsigned BN_num_bytes(const BIGNUM *bn); -// BN_zero sets |bn| to zero. +// BN_zero sets `bn` to zero. OPENSSL_EXPORT void BN_zero(BIGNUM *bn); -// BN_one sets |bn| to one. It returns one on success or zero on allocation +// BN_one sets `bn` to one. It returns one on success or zero on allocation // failure. OPENSSL_EXPORT int BN_one(BIGNUM *bn); -// BN_set_word sets |bn| to |value|. It returns one on success or zero on +// BN_set_word sets `bn` to `value`. It returns one on success or zero on // allocation failure. OPENSSL_EXPORT int BN_set_word(BIGNUM *bn, BN_ULONG value); -// BN_set_u64 sets |bn| to |value|. It returns one on success or zero on +// BN_set_u64 sets `bn` to `value`. It returns one on success or zero on // allocation failure. OPENSSL_EXPORT int BN_set_u64(BIGNUM *bn, uint64_t value); -// BN_set_negative sets the sign of |bn|. +// BN_set_negative sets the sign of `bn`. OPENSSL_EXPORT void BN_set_negative(BIGNUM *bn, int sign); -// BN_is_negative returns one if |bn| is negative and zero otherwise. +// BN_is_negative returns one if `bn` is negative and zero otherwise. OPENSSL_EXPORT int BN_is_negative(const BIGNUM *bn); // Conversion functions. -// BN_bin2bn sets |*ret| to the value of |len| bytes from |in|, interpreted as -// a big-endian number, and returns |ret|. If |ret| is NULL then a fresh -// |BIGNUM| is allocated and returned. It returns NULL on allocation +// BN_bin2bn sets `*ret` to the value of `len` bytes from `in`, interpreted as +// a big-endian number, and returns `ret`. If `ret` is NULL then a fresh +// `BIGNUM` is allocated and returned. It returns NULL on allocation // failure. OPENSSL_EXPORT BIGNUM *BN_bin2bn(const uint8_t *in, size_t len, BIGNUM *ret); -// BN_bn2bin serialises the absolute value of |in| to |out| as a big-endian -// integer, which must have |BN_num_bytes| of space available. It returns the -// number of bytes written. Note this function leaks the magnitude of |in|. If -// |in| is secret, use |BN_bn2bin_padded| instead. +// BN_bn2bin serialises the absolute value of `in` to `out` as a big-endian +// integer, which must have `BN_num_bytes` of space available. It returns the +// number of bytes written. Note this function leaks the magnitude of `in`. If +// `in` is secret, use `BN_bn2bin_padded` instead. OPENSSL_EXPORT size_t BN_bn2bin(const BIGNUM *in, uint8_t *out); -// BN_lebin2bn sets |*ret| to the value of |len| bytes from |in|, interpreted as -// a little-endian number, and returns |ret|. If |ret| is NULL then a fresh -// |BIGNUM| is allocated and returned. It returns NULL on allocation +// BN_lebin2bn sets `*ret` to the value of `len` bytes from `in`, interpreted as +// a little-endian number, and returns `ret`. If `ret` is NULL then a fresh +// `BIGNUM` is allocated and returned. It returns NULL on allocation // failure. OPENSSL_EXPORT BIGNUM *BN_lebin2bn(const uint8_t *in, size_t len, BIGNUM *ret); -// BN_bn2le_padded serialises the absolute value of |in| to |out| as a -// little-endian integer, which must have |len| of space available, padding -// out the remainder of out with zeros. If |len| is smaller than |BN_num_bytes|, +// BN_bn2le_padded serialises the absolute value of `in` to `out` as a +// little-endian integer, which must have `len` of space available, padding +// out the remainder of out with zeros. If `len` is smaller than `BN_num_bytes`, // the function fails and returns 0. Otherwise, it returns 1. OPENSSL_EXPORT int BN_bn2le_padded(uint8_t *out, size_t len, const BIGNUM *in); -// BN_bn2bin_padded serialises the absolute value of |in| to |out| as a +// BN_bn2bin_padded serialises the absolute value of `in` to `out` as a // big-endian integer. The integer is padded with leading zeros up to size -// |len|. If |len| is smaller than |BN_num_bytes|, the function fails and +// `len`. If `len` is smaller than `BN_num_bytes`, the function fails and // returns 0. Otherwise, it returns 1. OPENSSL_EXPORT int BN_bn2bin_padded(uint8_t *out, size_t len, const BIGNUM *in); -// BN_bn2cbb_padded behaves like |BN_bn2bin_padded| but writes to a |CBB|. +// BN_bn2cbb_padded behaves like `BN_bn2bin_padded` but writes to a `CBB`. OPENSSL_EXPORT int BN_bn2cbb_padded(CBB *out, size_t len, const BIGNUM *in); // BN_bn2hex returns an allocated string that contains a NUL-terminated, hex -// representation of |bn|. If |bn| is negative, the first char in the resulting +// representation of `bn`. If `bn` is negative, the first char in the resulting // string will be '-'. Returns NULL on allocation failure. OPENSSL_EXPORT char *BN_bn2hex(const BIGNUM *bn); -// BN_hex2bn parses the leading hex number from |in|, which may be proceeded by +// BN_hex2bn parses the leading hex number from `in`, which may be proceeded by // a '-' to indicate a negative number and may contain trailing, non-hex data. -// If |outp| is not NULL, it constructs a BIGNUM equal to the hex number and -// stores it in |*outp|. If |*outp| is NULL then it allocates a new BIGNUM and -// updates |*outp|. It returns the number of bytes of |in| processed or zero on +// If `outp` is not NULL, it constructs a BIGNUM equal to the hex number and +// stores it in `*outp`. If `*outp` is NULL then it allocates a new BIGNUM and +// updates `*outp`. It returns the number of bytes of `in` processed or zero on // error. OPENSSL_EXPORT int BN_hex2bn(BIGNUM **outp, const char *in); // BN_bn2dec returns an allocated string that contains a NUL-terminated, -// decimal representation of |bn|. If |bn| is negative, the first char in the +// decimal representation of `bn`. If `bn` is negative, the first char in the // resulting string will be '-'. Returns NULL on allocation failure. // // Converting an arbitrarily large integer to decimal is quadratic in the bit -// length of |a|. This function assumes the caller has capped the input within +// length of `a`. This function assumes the caller has capped the input within // performance tolerances. OPENSSL_EXPORT char *BN_bn2dec(const BIGNUM *a); -// BN_dec2bn parses the leading decimal number from |in|, which may be +// BN_dec2bn parses the leading decimal number from `in`, which may be // proceeded by a '-' to indicate a negative number and may contain trailing, -// non-decimal data. If |outp| is not NULL, it constructs a BIGNUM equal to the -// decimal number and stores it in |*outp|. If |*outp| is NULL then it -// allocates a new BIGNUM and updates |*outp|. It returns the number of bytes -// of |in| processed or zero on error. +// non-decimal data. If `outp` is not NULL, it constructs a BIGNUM equal to the +// decimal number and stores it in `*outp`. If `*outp` is NULL then it +// allocates a new BIGNUM and updates `*outp`. It returns the number of bytes +// of `in` processed or zero on error. // // Converting an arbitrarily large integer to decimal is quadratic in the bit -// length of |a|. This function assumes the caller has capped the input within +// length of `a`. This function assumes the caller has capped the input within // performance tolerances. OPENSSL_EXPORT int BN_dec2bn(BIGNUM **outp, const char *in); -// BN_asc2bn acts like |BN_dec2bn| or |BN_hex2bn| depending on whether |in| +// BN_asc2bn acts like `BN_dec2bn` or `BN_hex2bn` depending on whether `in` // begins with "0X" or "0x" (indicating hex) or not (indicating decimal). A // leading '-' is still permitted and comes before the optional 0X/0x. It // returns one on success or zero on error. OPENSSL_EXPORT int BN_asc2bn(BIGNUM **outp, const char *in); -// BN_print writes a hex encoding of |a| to |bio|. It returns one on success +// BN_print writes a hex encoding of `a` to `bio`. It returns one on success // and zero on error. OPENSSL_EXPORT int BN_print(BIO *bio, const BIGNUM *a); -// BN_print_fp acts like |BIO_print|, but wraps |fp| in a |BIO| first. +// BN_print_fp acts like `BIO_print`, but wraps `fp` in a `BIO` first. OPENSSL_EXPORT int BN_print_fp(FILE *fp, const BIGNUM *a); -// BN_get_word returns the absolute value of |bn| as a single word. If |bn| is +// BN_get_word returns the absolute value of `bn` as a single word. If `bn` is // too large to be represented as a single word, the maximum possible value // will be returned. OPENSSL_EXPORT BN_ULONG BN_get_word(const BIGNUM *bn); -// BN_get_u64 sets |*out| to the absolute value of |bn| as a |uint64_t| and -// returns one. If |bn| is too large to be represented as a |uint64_t|, it +// BN_get_u64 sets `*out` to the absolute value of `bn` as a `uint64_t` and +// returns one. If `bn` is too large to be represented as a `uint64_t`, it // returns zero. OPENSSL_EXPORT int BN_get_u64(const BIGNUM *bn, uint64_t *out); // ASN.1 functions. -// BN_parse_asn1_unsigned parses a non-negative DER INTEGER from |cbs| writes -// the result to |ret|. It returns one on success and zero on failure. +// BN_parse_asn1_unsigned parses a non-negative DER INTEGER from `cbs` writes +// the result to `ret`. It returns one on success and zero on failure. OPENSSL_EXPORT int BN_parse_asn1_unsigned(CBS *cbs, BIGNUM *ret); -// BN_marshal_asn1 marshals |bn| as a non-negative DER INTEGER and appends the -// result to |cbb|. It returns one on success and zero on failure. +// BN_marshal_asn1 marshals `bn` as a non-negative DER INTEGER and appends the +// result to `cbb`. It returns one on success and zero on failure. OPENSSL_EXPORT int BN_marshal_asn1(CBB *cbb, const BIGNUM *bn); @@ -240,100 +240,100 @@ // // Certain BIGNUM operations need to use many temporary variables and // allocating and freeing them can be quite slow. Thus such operations typically -// take a |BN_CTX| parameter, which contains a pool of |BIGNUMs|. The |ctx| -// argument to a public function may be NULL, in which case a local |BN_CTX| +// take a `BN_CTX` parameter, which contains a pool of `BIGNUMs`. The `ctx` +// argument to a public function may be NULL, in which case a local `BN_CTX` // will be created just for the lifetime of that call. // -// A function must call |BN_CTX_start| first. Then, |BN_CTX_get| may be called -// repeatedly to obtain temporary |BIGNUM|s. All |BN_CTX_get| calls must be made -// before calling any other functions that use the |ctx| as an argument. +// A function must call `BN_CTX_start` first. Then, `BN_CTX_get` may be called +// repeatedly to obtain temporary `BIGNUM`s. All `BN_CTX_get` calls must be made +// before calling any other functions that use the `ctx` as an argument. // -// Finally, |BN_CTX_end| must be called before returning from the function. -// When |BN_CTX_end| is called, the |BIGNUM| pointers obtained from -// |BN_CTX_get| become invalid. +// Finally, `BN_CTX_end` must be called before returning from the function. +// When `BN_CTX_end` is called, the `BIGNUM` pointers obtained from +// `BN_CTX_get` become invalid. // BN_CTX_new returns a new, empty BN_CTX or NULL on allocation failure. OPENSSL_EXPORT BN_CTX *BN_CTX_new(void); -// BN_CTX_free frees all BIGNUMs contained in |ctx| and then frees |ctx| +// BN_CTX_free frees all BIGNUMs contained in `ctx` and then frees `ctx` // itself. OPENSSL_EXPORT void BN_CTX_free(BN_CTX *ctx); -// BN_CTX_start "pushes" a new entry onto the |ctx| stack and allows future -// calls to |BN_CTX_get|. +// BN_CTX_start "pushes" a new entry onto the `ctx` stack and allows future +// calls to `BN_CTX_get`. OPENSSL_EXPORT void BN_CTX_start(BN_CTX *ctx); -// BN_CTX_get returns a new |BIGNUM|, or NULL on allocation failure. Once -// |BN_CTX_get| has returned NULL, all future calls will also return NULL until -// |BN_CTX_end| is called. +// BN_CTX_get returns a new `BIGNUM`, or NULL on allocation failure. Once +// `BN_CTX_get` has returned NULL, all future calls will also return NULL until +// `BN_CTX_end` is called. OPENSSL_EXPORT BIGNUM *BN_CTX_get(BN_CTX *ctx); -// BN_CTX_end invalidates all |BIGNUM|s returned from |BN_CTX_get| since the -// matching |BN_CTX_start| call. +// BN_CTX_end invalidates all `BIGNUM`s returned from `BN_CTX_get` since the +// matching `BN_CTX_start` call. OPENSSL_EXPORT void BN_CTX_end(BN_CTX *ctx); // Simple arithmetic -// BN_add sets |r| = |a| + |b|, where |r| may be the same pointer as either |a| -// or |b|. It returns one on success and zero on allocation failure. +// BN_add sets `r` = `a` + `b`, where `r` may be the same pointer as either `a` +// or `b`. It returns one on success and zero on allocation failure. OPENSSL_EXPORT int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); -// BN_uadd sets |r| = |a| + |b|, considering only the absolute values of |a| and -// |b|. |r| may be the same pointer as either |a| or |b|. It returns one on +// BN_uadd sets `r` = `a` + `b`, considering only the absolute values of `a` and +// `b`. `r` may be the same pointer as either `a` or `b`. It returns one on // success and zero on allocation failure. OPENSSL_EXPORT int BN_uadd(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); -// BN_add_word adds |w| to |a|. It returns one on success and zero otherwise. +// BN_add_word adds `w` to `a`. It returns one on success and zero otherwise. OPENSSL_EXPORT int BN_add_word(BIGNUM *a, BN_ULONG w); -// BN_sub sets |r| = |a| - |b|, where |r| may be the same pointer as either |a| -// or |b|. It returns one on success and zero on allocation failure. +// BN_sub sets `r` = `a` - `b`, where `r` may be the same pointer as either `a` +// or `b`. It returns one on success and zero on allocation failure. OPENSSL_EXPORT int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); -// BN_usub sets |r| = |a| - |b|, considering only the absolute values of |a| and -// |b|. The result must be non-negative, i.e. |b| <= |a|. |r| may be the same -// pointer as either |a| or |b|. It returns one on success and zero on error. +// BN_usub sets `r` = `a` - `b`, considering only the absolute values of `a` and +// `b`. The result must be non-negative, i.e. `b` <= `a`. `r` may be the same +// pointer as either `a` or `b`. It returns one on success and zero on error. OPENSSL_EXPORT int BN_usub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); -// BN_sub_word subtracts |w| from |a|. It returns one on success and zero on +// BN_sub_word subtracts `w` from `a`. It returns one on success and zero on // allocation failure. OPENSSL_EXPORT int BN_sub_word(BIGNUM *a, BN_ULONG w); -// BN_mul sets |r| = |a| * |b|, where |r| may be the same pointer as |a| or -// |b|. Returns one on success and zero otherwise. +// BN_mul sets `r` = `a` * `b`, where `r` may be the same pointer as `a` or +// `b`. Returns one on success and zero otherwise. OPENSSL_EXPORT int BN_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); -// BN_mul_word sets |bn| = |bn| * |w|. It returns one on success or zero on +// BN_mul_word sets `bn` = `bn` * `w`. It returns one on success or zero on // allocation failure. OPENSSL_EXPORT int BN_mul_word(BIGNUM *bn, BN_ULONG w); -// BN_sqr sets |r| = |a|^2 (i.e. squares), where |r| may be the same pointer as -// |a|. Returns one on success and zero otherwise. This is more efficient than +// BN_sqr sets `r` = `a`^2 (i.e. squares), where `r` may be the same pointer as +// `a`. Returns one on success and zero otherwise. This is more efficient than // BN_mul(r, a, a, ctx). OPENSSL_EXPORT int BN_sqr(BIGNUM *r, const BIGNUM *a, BN_CTX *ctx); -// BN_div divides |numerator| by |divisor| and places the result in |quotient| -// and the remainder in |rem|. Either of |quotient| or |rem| may be NULL, in +// BN_div divides `numerator` by `divisor` and places the result in `quotient` +// and the remainder in `rem`. Either of `quotient` or `rem` may be NULL, in // which case the respective value is not returned. It returns one on success or -// zero on error. It is an error condition if |divisor| is zero. +// zero on error. It is an error condition if `divisor` is zero. // -// The outputs will be such that |quotient| * |divisor| + |rem| = |numerator|, -// with the quotient rounded towards zero. Thus, if |numerator| is negative, -// |rem| will be zero or negative. If |divisor| is negative, the sign of -// |quotient| will be flipped to compensate but otherwise rounding will be as if -// |divisor| were its absolute value. +// The outputs will be such that `quotient` * `divisor` + `rem` = `numerator`, +// with the quotient rounded towards zero. Thus, if `numerator` is negative, +// `rem` will be zero or negative. If `divisor` is negative, the sign of +// `quotient` will be flipped to compensate but otherwise rounding will be as if +// `divisor` were its absolute value. OPENSSL_EXPORT int BN_div(BIGNUM *quotient, BIGNUM *rem, const BIGNUM *numerator, const BIGNUM *divisor, BN_CTX *ctx); -// BN_div_word sets |numerator| = |numerator|/|divisor| and returns the +// BN_div_word sets `numerator` = `numerator`/`divisor` and returns the // remainder or (BN_ULONG)-1 on error. OPENSSL_EXPORT BN_ULONG BN_div_word(BIGNUM *numerator, BN_ULONG divisor); -// BN_sqrt sets |*out_sqrt| (which may be the same |BIGNUM| as |in|) to the -// square root of |in|, using |ctx|. It returns one on success or zero on +// BN_sqrt sets `*out_sqrt` (which may be the same `BIGNUM` as `in`) to the +// square root of `in`, using `ctx`. It returns one on success or zero on // error. Negative numbers and non-square numbers will result in an error with // appropriate errors on the error queue. OPENSSL_EXPORT int BN_sqrt(BIGNUM *out_sqrt, const BIGNUM *in, BN_CTX *ctx); @@ -341,213 +341,213 @@ // Comparison functions -// BN_cmp returns a value less than, equal to or greater than zero if |a| is -// less than, equal to or greater than |b|, respectively. +// BN_cmp returns a value less than, equal to or greater than zero if `a` is +// less than, equal to or greater than `b`, respectively. OPENSSL_EXPORT int BN_cmp(const BIGNUM *a, const BIGNUM *b); -// BN_cmp_word is like |BN_cmp| except it takes its second argument as a -// |BN_ULONG| instead of a |BIGNUM|. +// BN_cmp_word is like `BN_cmp` except it takes its second argument as a +// `BN_ULONG` instead of a `BIGNUM`. OPENSSL_EXPORT int BN_cmp_word(const BIGNUM *a, BN_ULONG b); // BN_ucmp returns a value less than, equal to or greater than zero if the -// absolute value of |a| is less than, equal to or greater than the absolute -// value of |b|, respectively. +// absolute value of `a` is less than, equal to or greater than the absolute +// value of `b`, respectively. OPENSSL_EXPORT int BN_ucmp(const BIGNUM *a, const BIGNUM *b); -// BN_equal_consttime returns one if |a| is equal to |b|, and zero otherwise. -// It takes an amount of time dependent on the sizes of |a| and |b|, but -// independent of the contents (including the signs) of |a| and |b|. +// BN_equal_consttime returns one if `a` is equal to `b`, and zero otherwise. +// It takes an amount of time dependent on the sizes of `a` and `b`, but +// independent of the contents (including the signs) of `a` and `b`. OPENSSL_EXPORT int BN_equal_consttime(const BIGNUM *a, const BIGNUM *b); -// BN_abs_is_word returns one if the absolute value of |bn| equals |w| and zero +// BN_abs_is_word returns one if the absolute value of `bn` equals `w` and zero // otherwise. OPENSSL_EXPORT int BN_abs_is_word(const BIGNUM *bn, BN_ULONG w); -// BN_is_zero returns one if |bn| is zero and zero otherwise. +// BN_is_zero returns one if `bn` is zero and zero otherwise. OPENSSL_EXPORT int BN_is_zero(const BIGNUM *bn); -// BN_is_one returns one if |bn| equals one and zero otherwise. +// BN_is_one returns one if `bn` equals one and zero otherwise. OPENSSL_EXPORT int BN_is_one(const BIGNUM *bn); -// BN_is_word returns one if |bn| is exactly |w| and zero otherwise. +// BN_is_word returns one if `bn` is exactly `w` and zero otherwise. OPENSSL_EXPORT int BN_is_word(const BIGNUM *bn, BN_ULONG w); -// BN_is_odd returns one if |bn| is odd and zero otherwise. +// BN_is_odd returns one if `bn` is odd and zero otherwise. OPENSSL_EXPORT int BN_is_odd(const BIGNUM *bn); -// BN_is_pow2 returns 1 if |a| is a power of two, and 0 otherwise. +// BN_is_pow2 returns 1 if `a` is a power of two, and 0 otherwise. OPENSSL_EXPORT int BN_is_pow2(const BIGNUM *a); // Bitwise operations. -// BN_lshift sets |r| equal to |a| << n. The |a| and |r| arguments may be the -// same |BIGNUM|. It returns one on success and zero on allocation failure. +// BN_lshift sets `r` equal to `a` << n. The `a` and `r` arguments may be the +// same `BIGNUM`. It returns one on success and zero on allocation failure. OPENSSL_EXPORT int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); -// BN_lshift1 sets |r| equal to |a| << 1, where |r| and |a| may be the same +// BN_lshift1 sets `r` equal to `a` << 1, where `r` and `a` may be the same // pointer. It returns one on success and zero on allocation failure. OPENSSL_EXPORT int BN_lshift1(BIGNUM *r, const BIGNUM *a); -// BN_rshift sets |r| equal to |a| >> n, where |r| and |a| may be the same +// BN_rshift sets `r` equal to `a` >> n, where `r` and `a` may be the same // pointer. It returns one on success and zero on allocation failure. OPENSSL_EXPORT int BN_rshift(BIGNUM *r, const BIGNUM *a, int n); -// BN_rshift1 sets |r| equal to |a| >> 1, where |r| and |a| may be the same +// BN_rshift1 sets `r` equal to `a` >> 1, where `r` and `a` may be the same // pointer. It returns one on success and zero on allocation failure. OPENSSL_EXPORT int BN_rshift1(BIGNUM *r, const BIGNUM *a); -// BN_set_bit sets the |n|th, least-significant bit in |a|. For example, if |a| +// BN_set_bit sets the `n`th, least-significant bit in `a`. For example, if `a` // is 2 then setting bit zero will make it 3. It returns one on success or zero // on allocation failure. OPENSSL_EXPORT int BN_set_bit(BIGNUM *a, int n); -// BN_clear_bit clears the |n|th, least-significant bit in |a|. For example, if -// |a| is 3, clearing bit zero will make it two. It returns one on success or +// BN_clear_bit clears the `n`th, least-significant bit in `a`. For example, if +// `a` is 3, clearing bit zero will make it two. It returns one on success or // zero on allocation failure. OPENSSL_EXPORT int BN_clear_bit(BIGNUM *a, int n); -// BN_is_bit_set returns one if the |n|th least-significant bit in |a| exists +// BN_is_bit_set returns one if the `n`th least-significant bit in `a` exists // and is set. Otherwise, it returns zero. OPENSSL_EXPORT int BN_is_bit_set(const BIGNUM *a, int n); -// BN_mask_bits truncates |a| so that it is only |n| bits long. It returns one -// on success or zero if |n| is negative. +// BN_mask_bits truncates `a` so that it is only `n` bits long. It returns one +// on success or zero if `n` is negative. // -// This differs from OpenSSL which additionally returns zero if |a|'s word -// length is less than or equal to |n|, rounded down to a number of words. Note +// This differs from OpenSSL which additionally returns zero if `a`'s word +// length is less than or equal to `n`, rounded down to a number of words. Note // word size is platform-dependent, so this behavior is also difficult to rely // on in OpenSSL and not very useful. OPENSSL_EXPORT int BN_mask_bits(BIGNUM *a, int n); -// BN_count_low_zero_bits returns the number of low-order zero bits in |bn|, or -// the number of factors of two which divide it. It returns zero if |bn| is +// BN_count_low_zero_bits returns the number of low-order zero bits in `bn`, or +// the number of factors of two which divide it. It returns zero if `bn` is // zero. OPENSSL_EXPORT int BN_count_low_zero_bits(const BIGNUM *bn); // Modulo arithmetic. -// BN_mod_word returns |a| mod |w| or (BN_ULONG)-1 on error. +// BN_mod_word returns `a` mod `w` or (BN_ULONG)-1 on error. OPENSSL_EXPORT BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); -// BN_mod_pow2 sets |r| = |a| mod 2^|e|. It returns 1 on success and +// BN_mod_pow2 sets `r` = `a` mod 2^`e`. It returns 1 on success and // 0 on error. OPENSSL_EXPORT int BN_mod_pow2(BIGNUM *r, const BIGNUM *a, size_t e); -// BN_nnmod_pow2 sets |r| = |a| mod 2^|e| where |r| is always positive. +// BN_nnmod_pow2 sets `r` = `a` mod 2^`e` where `r` is always positive. // It returns 1 on success and 0 on error. OPENSSL_EXPORT int BN_nnmod_pow2(BIGNUM *r, const BIGNUM *a, size_t e); -// BN_mod is a helper macro that calls |BN_div| and discards the quotient. +// BN_mod is a helper macro that calls `BN_div` and discards the quotient. #define BN_mod(rem, numerator, divisor, ctx) \ BN_div(NULL, (rem), (numerator), (divisor), (ctx)) -// BN_nnmod is a non-negative modulo function. It acts like |BN_mod|, but 0 <= -// |rem| < |divisor| is always true. It returns one on success and zero on +// BN_nnmod is a non-negative modulo function. It acts like `BN_mod`, but 0 <= +// `rem` < `divisor` is always true. It returns one on success and zero on // error. OPENSSL_EXPORT int BN_nnmod(BIGNUM *rem, const BIGNUM *numerator, const BIGNUM *divisor, BN_CTX *ctx); -// BN_mod_add sets |r| = |a| + |b| mod |m|. It returns one on success and zero +// BN_mod_add sets `r` = `a` + `b` mod `m`. It returns one on success and zero // on error. OPENSSL_EXPORT int BN_mod_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); -// BN_mod_add_quick acts like |BN_mod_add| but requires that |a| and |b| be -// non-negative and less than |m|. +// BN_mod_add_quick acts like `BN_mod_add` but requires that `a` and `b` be +// non-negative and less than `m`. OPENSSL_EXPORT int BN_mod_add_quick(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m); -// BN_mod_sub sets |r| = |a| - |b| mod |m|. It returns one on success and zero +// BN_mod_sub sets `r` = `a` - `b` mod `m`. It returns one on success and zero // on error. OPENSSL_EXPORT int BN_mod_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); -// BN_mod_sub_quick acts like |BN_mod_sub| but requires that |a| and |b| be -// non-negative and less than |m|. +// BN_mod_sub_quick acts like `BN_mod_sub` but requires that `a` and `b` be +// non-negative and less than `m`. OPENSSL_EXPORT int BN_mod_sub_quick(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m); -// BN_mod_mul sets |r| = |a|*|b| mod |m|. It returns one on success and zero +// BN_mod_mul sets `r` = `a`*`b` mod `m`. It returns one on success and zero // on error. OPENSSL_EXPORT int BN_mod_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); -// BN_mod_sqr sets |r| = |a|^2 mod |m|. It returns one on success and zero +// BN_mod_sqr sets `r` = `a`^2 mod `m`. It returns one on success and zero // on error. OPENSSL_EXPORT int BN_mod_sqr(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); -// BN_mod_lshift sets |r| = (|a| << n) mod |m|, where |r| and |a| may be the +// BN_mod_lshift sets `r` = (`a` << n) mod `m`, where `r` and `a` may be the // same pointer. It returns one on success and zero on error. OPENSSL_EXPORT int BN_mod_lshift(BIGNUM *r, const BIGNUM *a, int n, const BIGNUM *m, BN_CTX *ctx); -// BN_mod_lshift_quick acts like |BN_mod_lshift| but requires that |a| be -// non-negative and less than |m|. +// BN_mod_lshift_quick acts like `BN_mod_lshift` but requires that `a` be +// non-negative and less than `m`. OPENSSL_EXPORT int BN_mod_lshift_quick(BIGNUM *r, const BIGNUM *a, int n, const BIGNUM *m); -// BN_mod_lshift1 sets |r| = (|a| << 1) mod |m|, where |r| and |a| may be the +// BN_mod_lshift1 sets `r` = (`a` << 1) mod `m`, where `r` and `a` may be the // same pointer. It returns one on success and zero on error. OPENSSL_EXPORT int BN_mod_lshift1(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); -// BN_mod_lshift1_quick acts like |BN_mod_lshift1| but requires that |a| be -// non-negative and less than |m|. +// BN_mod_lshift1_quick acts like `BN_mod_lshift1` but requires that `a` be +// non-negative and less than `m`. OPENSSL_EXPORT int BN_mod_lshift1_quick(BIGNUM *r, const BIGNUM *a, const BIGNUM *m); -// BN_mod_sqrt returns a newly-allocated |BIGNUM|, r, such that -// r^2 == a (mod p). It returns NULL on error or if |a| is not a square mod |p|. -// In the latter case, it will add |BN_R_NOT_A_SQUARE| to the error queue. -// If |a| is a square and |p| > 2, there are two possible square roots. This +// BN_mod_sqrt returns a newly-allocated `BIGNUM`, r, such that +// r^2 == a (mod p). It returns NULL on error or if `a` is not a square mod `p`. +// In the latter case, it will add `BN_R_NOT_A_SQUARE` to the error queue. +// If `a` is a square and `p` > 2, there are two possible square roots. This // function may return either and may even select one non-deterministically. // -// If |in| is non-NULL, the function, instead of allocating the result, stores -// the result in |in| and returns |in| on success or NULL on failure. +// If `in` is non-NULL, the function, instead of allocating the result, stores +// the result in `in` and returns `in` on success or NULL on failure. // -// This function only works if |p| is a prime. If |p| is composite, it may fail +// This function only works if `p` is a prime. If `p` is composite, it may fail // or return an arbitrary value. Callers should not pass attacker-controlled -// values of |p|. +// values of `p`. OPENSSL_EXPORT BIGNUM *BN_mod_sqrt(BIGNUM *in, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx); // Random and prime number generation. -// The following are values for the |top| parameter of |BN_rand|. +// The following are values for the `top` parameter of `BN_rand`. #define BN_RAND_TOP_ANY (-1) #define BN_RAND_TOP_ONE 0 #define BN_RAND_TOP_TWO 1 -// The following are values for the |bottom| parameter of |BN_rand|. +// The following are values for the `bottom` parameter of `BN_rand`. #define BN_RAND_BOTTOM_ANY 0 #define BN_RAND_BOTTOM_ODD 1 -// BN_rand sets |rnd| to a random number of length |bits|. It returns one on +// BN_rand sets `rnd` to a random number of length `bits`. It returns one on // success and zero otherwise. // -// |top| must be one of the |BN_RAND_TOP_*| values. If |BN_RAND_TOP_ONE|, the -// most-significant bit, if any, will be set. If |BN_RAND_TOP_TWO|, the two -// most significant bits, if any, will be set. If |BN_RAND_TOP_ANY|, no extra -// action will be taken and |BN_num_bits(rnd)| may not equal |bits| if the most +// `top` must be one of the `BN_RAND_TOP_*` values. If `BN_RAND_TOP_ONE`, the +// most-significant bit, if any, will be set. If `BN_RAND_TOP_TWO`, the two +// most significant bits, if any, will be set. If `BN_RAND_TOP_ANY`, no extra +// action will be taken and `BN_num_bits(rnd)` may not equal `bits` if the most // significant bits randomly ended up as zeros. // -// |bottom| must be one of the |BN_RAND_BOTTOM_*| values. If -// |BN_RAND_BOTTOM_ODD|, the least-significant bit, if any, will be set. If -// |BN_RAND_BOTTOM_ANY|, no extra action will be taken. +// `bottom` must be one of the `BN_RAND_BOTTOM_*` values. If +// `BN_RAND_BOTTOM_ODD`, the least-significant bit, if any, will be set. If +// `BN_RAND_BOTTOM_ANY`, no extra action will be taken. OPENSSL_EXPORT int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); -// BN_pseudo_rand is an alias for |BN_rand|. +// BN_pseudo_rand is an alias for `BN_rand`. OPENSSL_EXPORT int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); -// BN_rand_range is equivalent to |BN_rand_range_ex| with |min_inclusive| set -// to zero and |max_exclusive| set to |range|. +// BN_rand_range is equivalent to `BN_rand_range_ex` with `min_inclusive` set +// to zero and `max_exclusive` set to `range`. OPENSSL_EXPORT int BN_rand_range(BIGNUM *rnd, const BIGNUM *range); -// BN_rand_range_ex sets |rnd| to a random value in +// BN_rand_range_ex sets `rnd` to a random value in // [min_inclusive..max_exclusive). It returns one on success and zero // otherwise. OPENSSL_EXPORT int BN_rand_range_ex(BIGNUM *r, BN_ULONG min_inclusive, @@ -559,12 +559,12 @@ #define BN_GENCB_GENERATED 0 #define BN_GENCB_PRIME_TEST 1 -// bn_gencb_st, or |BN_GENCB|, holds a callback function that is used by +// bn_gencb_st, or `BN_GENCB`, holds a callback function that is used by // generation functions that can take a very long time to complete. Use -// |BN_GENCB_set| to initialise a |BN_GENCB| structure. +// `BN_GENCB_set` to initialise a `BN_GENCB` structure. // -// The callback receives the address of that |BN_GENCB| structure as its last -// argument and the user is free to put an arbitrary pointer in |arg|. The other +// The callback receives the address of that `BN_GENCB` structure as its last +// argument and the user is free to put an arbitrary pointer in `arg`. The other // arguments are set as follows: // - event=BN_GENCB_GENERATED, n=i: after generating the i'th possible prime // number. @@ -582,57 +582,57 @@ int (*callback)(int event, int n, struct bn_gencb_st *); }; -// BN_GENCB_new returns a newly-allocated |BN_GENCB| object, or NULL on -// allocation failure. The result must be released with |BN_GENCB_free| when +// BN_GENCB_new returns a newly-allocated `BN_GENCB` object, or NULL on +// allocation failure. The result must be released with `BN_GENCB_free` when // done. OPENSSL_EXPORT BN_GENCB *BN_GENCB_new(void); -// BN_GENCB_free releases memory associated with |callback|. +// BN_GENCB_free releases memory associated with `callback`. OPENSSL_EXPORT void BN_GENCB_free(BN_GENCB *callback); -// BN_GENCB_set configures |callback| to call |f| and sets |callout->arg| to -// |arg|. +// BN_GENCB_set configures `callback` to call `f` and sets `callout->arg` to +// `arg`. OPENSSL_EXPORT void BN_GENCB_set(BN_GENCB *callback, int (*f)(int event, int n, BN_GENCB *), void *arg); -// BN_GENCB_call calls |callback|, if not NULL, and returns the return value of -// the callback, or 1 if |callback| is NULL. +// BN_GENCB_call calls `callback`, if not NULL, and returns the return value of +// the callback, or 1 if `callback` is NULL. OPENSSL_EXPORT int BN_GENCB_call(BN_GENCB *callback, int event, int n); -// BN_GENCB_get_arg returns |callback->arg|. +// BN_GENCB_get_arg returns `callback->arg`. OPENSSL_EXPORT void *BN_GENCB_get_arg(const BN_GENCB *callback); -// BN_generate_prime_ex sets |ret| to a prime number of |bits| length. If safe +// BN_generate_prime_ex sets `ret` to a prime number of `bits` length. If safe // is non-zero then the prime will be such that (ret-1)/2 is also a prime. // (This is needed for Diffie-Hellman groups to ensure that the only subgroups // are of size 2 and (p-1)/2.). // -// If |add| is not NULL, the prime will fulfill the condition |ret| % |add| == -// |rem| in order to suit a given generator. (If |rem| is NULL then |ret| % -// |add| == 1.) +// If `add` is not NULL, the prime will fulfill the condition `ret` % `add` == +// `rem` in order to suit a given generator. (If `rem` is NULL then `ret` % +// `add` == 1.) // -// If |cb| is not NULL, it will be called during processing to give an -// indication of progress. See the comments for |BN_GENCB|. It returns one on +// If `cb` is not NULL, it will be called during processing to give an +// indication of progress. See the comments for `BN_GENCB`. It returns one on // success and zero otherwise. OPENSSL_EXPORT int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb); -// BN_prime_checks_for_validation can be used as the |checks| argument to the +// BN_prime_checks_for_validation can be used as the `checks` argument to the // primarily testing functions when validating an externally-supplied candidate // prime. It gives a false positive rate of at most 2^{-128}. (The worst case // false positive rate for a single iteration is 1/4 per // https://eprint.iacr.org/2018/749. (1/4)^64 = 2^{-128}.) #define BN_prime_checks_for_validation 64 -// BN_prime_checks_for_generation can be used as the |checks| argument to the +// BN_prime_checks_for_generation can be used as the `checks` argument to the // primality testing functions when generating random primes. It gives a false // positive rate at most the security level of the corresponding RSA key size. // // Note this value only performs enough checks if the candidate prime was // selected randomly. If validating an externally-supplied candidate, especially -// one that may be selected adversarially, use |BN_prime_checks_for_validation| +// one that may be selected adversarially, use `BN_prime_checks_for_validation` // instead. #define BN_prime_checks_for_generation 0 @@ -643,34 +643,34 @@ bn_non_prime_power_composite, }; -// BN_enhanced_miller_rabin_primality_test tests whether |w| is probably a prime +// BN_enhanced_miller_rabin_primality_test tests whether `w` is probably a prime // number using the Enhanced Miller-Rabin Test (FIPS 186-5 B.3.2) with -// |checks| iterations and returns the result in |out_result|. Enhanced +// `checks` iterations and returns the result in `out_result`. Enhanced // Miller-Rabin tests primality for odd integers greater than 3, returning -// |bn_probably_prime| if the number is probably prime, -// |bn_non_prime_power_composite| if the number is a composite that is not the -// power of a single prime, and |bn_composite| otherwise. It returns one on -// success and zero on failure. If |cb| is not NULL, then it is called during +// `bn_probably_prime` if the number is probably prime, +// `bn_non_prime_power_composite` if the number is a composite that is not the +// power of a single prime, and `bn_composite` otherwise. It returns one on +// success and zero on failure. If `cb` is not NULL, then it is called during // each iteration of the primality test. // -// See |BN_prime_checks_for_validation| and |BN_prime_checks_for_generation| for -// recommended values of |checks|. +// See `BN_prime_checks_for_validation` and `BN_prime_checks_for_generation` for +// recommended values of `checks`. OPENSSL_EXPORT int BN_enhanced_miller_rabin_primality_test( enum bn_primality_result_t *out_result, const BIGNUM *w, int checks, BN_CTX *ctx, BN_GENCB *cb); -// BN_primality_test sets |*is_probably_prime| to one if |candidate| is +// BN_primality_test sets `*is_probably_prime` to one if `candidate` is // probably a prime number by the Miller-Rabin test or zero if it's certainly // not. // -// If |do_trial_division| is non-zero then |candidate| will be tested against a +// If `do_trial_division` is non-zero then `candidate` will be tested against a // list of small primes before Miller-Rabin tests. The probability of this // function returning a false positive is at most 2^{2*checks}. See -// |BN_prime_checks_for_validation| and |BN_prime_checks_for_generation| for -// recommended values of |checks|. +// `BN_prime_checks_for_validation` and `BN_prime_checks_for_generation` for +// recommended values of `checks`. // -// If |cb| is not NULL then it is called during the checking process. See the -// comment above |BN_GENCB|. +// If `cb` is not NULL then it is called during the checking process. See the +// comment above `BN_GENCB`. // // The function returns one on success and zero on error. OPENSSL_EXPORT int BN_primality_test(int *is_probably_prime, @@ -678,72 +678,72 @@ BN_CTX *ctx, int do_trial_division, BN_GENCB *cb); -// BN_is_prime_fasttest_ex returns one if |candidate| is probably a prime +// BN_is_prime_fasttest_ex returns one if `candidate` is probably a prime // number by the Miller-Rabin test, zero if it's certainly not and -1 on error. // -// If |do_trial_division| is non-zero then |candidate| will be tested against a +// If `do_trial_division` is non-zero then `candidate` will be tested against a // list of small primes before Miller-Rabin tests. The probability of this -// function returning one when |candidate| is composite is at most 2^{2*checks}. -// See |BN_prime_checks_for_validation| and |BN_prime_checks_for_generation| for -// recommended values of |checks|. +// function returning one when `candidate` is composite is at most 2^{2*checks}. +// See `BN_prime_checks_for_validation` and `BN_prime_checks_for_generation` for +// recommended values of `checks`. // -// If |cb| is not NULL then it is called during the checking process. See the -// comment above |BN_GENCB|. +// If `cb` is not NULL then it is called during the checking process. See the +// comment above `BN_GENCB`. // -// WARNING: deprecated. Use |BN_primality_test|. +// WARNING: deprecated. Use `BN_primality_test`. OPENSSL_EXPORT int BN_is_prime_fasttest_ex(const BIGNUM *candidate, int checks, BN_CTX *ctx, int do_trial_division, BN_GENCB *cb); -// BN_is_prime_ex acts the same as |BN_is_prime_fasttest_ex| with -// |do_trial_division| set to zero. +// BN_is_prime_ex acts the same as `BN_is_prime_fasttest_ex` with +// `do_trial_division` set to zero. // -// WARNING: deprecated: Use |BN_primality_test|. +// WARNING: deprecated: Use `BN_primality_test`. OPENSSL_EXPORT int BN_is_prime_ex(const BIGNUM *candidate, int checks, BN_CTX *ctx, BN_GENCB *cb); // Number theory functions -// BN_gcd sets |r| = gcd(|a|, |b|). It returns one on success and zero +// BN_gcd sets `r` = gcd(`a`, `b`). It returns one on success and zero // otherwise. OPENSSL_EXPORT int BN_gcd(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); -// BN_mod_inverse sets |out| equal to |a|^-1, mod |n|. If |out| is NULL, a +// BN_mod_inverse sets `out` equal to `a`^-1, mod `n`. If `out` is NULL, a // fresh BIGNUM is allocated. It returns the result or NULL on error. // -// If |n| is even then the operation is performed using an algorithm that avoids +// If `n` is even then the operation is performed using an algorithm that avoids // some branches but which isn't constant-time. This function shouldn't be used -// for secret values; use |BN_mod_inverse_blinded| instead. Or, if |n| is +// for secret values; use `BN_mod_inverse_blinded` instead. Or, if `n` is // guaranteed to be prime, use -// |BN_mod_exp_mont_consttime(out, a, m_minus_2, m, ctx, m_mont)|, taking +// `BN_mod_exp_mont_consttime(out, a, m_minus_2, m, ctx, m_mont)`, taking // advantage of Fermat's Little Theorem. OPENSSL_EXPORT BIGNUM *BN_mod_inverse(BIGNUM *out, const BIGNUM *a, const BIGNUM *n, BN_CTX *ctx); -// BN_mod_inverse_blinded sets |out| equal to |a|^-1, mod |n|, where |n| is the -// Montgomery modulus for |mont|. |a| must be non-negative and must be less -// than |n|. |n| must be greater than 1. |a| is blinded (masked by a random +// BN_mod_inverse_blinded sets `out` equal to `a`^-1, mod `n`, where `n` is the +// Montgomery modulus for `mont`. `a` must be non-negative and must be less +// than `n`. `n` must be greater than 1. `a` is blinded (masked by a random // value) to protect it against side-channel attacks. On failure, if the failure -// was caused by |a| having no inverse mod |n| then |*out_no_inverse| will be +// was caused by `a` having no inverse mod `n` then `*out_no_inverse` will be // set to one; otherwise it will be set to zero. // -// Note this function may incorrectly report |a| has no inverse if the random -// blinding value has no inverse. It should only be used when |n| has few +// Note this function may incorrectly report `a` has no inverse if the random +// blinding value has no inverse. It should only be used when `n` has few // non-invertible elements, such as an RSA modulus. OPENSSL_EXPORT int BN_mod_inverse_blinded(BIGNUM *out, int *out_no_inverse, const BIGNUM *a, const BN_MONT_CTX *mont, BN_CTX *ctx); -// BN_mod_inverse_odd sets |out| equal to |a|^-1, mod |n|. |a| must be -// non-negative and must be less than |n|. |n| must be odd. This function -// shouldn't be used for secret values; use |BN_mod_inverse_blinded| instead. -// Or, if |n| is guaranteed to be prime, use -// |BN_mod_exp_mont_consttime(out, a, m_minus_2, m, ctx, m_mont)|, taking +// BN_mod_inverse_odd sets `out` equal to `a`^-1, mod `n`. `a` must be +// non-negative and must be less than `n`. `n` must be odd. This function +// shouldn't be used for secret values; use `BN_mod_inverse_blinded` instead. +// Or, if `n` is guaranteed to be prime, use +// `BN_mod_exp_mont_consttime(out, a, m_minus_2, m, ctx, m_mont)`, taking // advantage of Fermat's Little Theorem. It returns one on success or zero on -// failure. On failure, if the failure was caused by |a| having no inverse mod -// |n| then |*out_no_inverse| will be set to one; otherwise it will be set to +// failure. On failure, if the failure was caused by `a` having no inverse mod +// `n` then `*out_no_inverse` will be set to one; otherwise it will be set to // zero. int BN_mod_inverse_odd(BIGNUM *out, int *out_no_inverse, const BIGNUM *a, const BIGNUM *n, BN_CTX *ctx); @@ -754,41 +754,41 @@ // BN_MONT_CTX contains the precomputed values needed to work in a specific // Montgomery domain. -// BN_MONT_CTX_new_for_modulus returns a fresh |BN_MONT_CTX| given the modulus, -// |mod| or NULL on error. Note this function assumes |mod| is public. +// BN_MONT_CTX_new_for_modulus returns a fresh `BN_MONT_CTX` given the modulus, +// `mod` or NULL on error. Note this function assumes `mod` is public. OPENSSL_EXPORT BN_MONT_CTX *BN_MONT_CTX_new_for_modulus(const BIGNUM *mod, BN_CTX *ctx); -// BN_MONT_CTX_new_consttime behaves like |BN_MONT_CTX_new_for_modulus| but -// treats |mod| as secret. +// BN_MONT_CTX_new_consttime behaves like `BN_MONT_CTX_new_for_modulus` but +// treats `mod` as secret. OPENSSL_EXPORT BN_MONT_CTX *BN_MONT_CTX_new_consttime(const BIGNUM *mod, BN_CTX *ctx); -// BN_MONT_CTX_free frees memory associated with |mont|. +// BN_MONT_CTX_free frees memory associated with `mont`. OPENSSL_EXPORT void BN_MONT_CTX_free(BN_MONT_CTX *mont); -// BN_MONT_CTX_copy sets |to| equal to |from|. It returns |to| on success or +// BN_MONT_CTX_copy sets `to` equal to `from`. It returns `to` on success or // NULL on error. OPENSSL_EXPORT BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, const BN_MONT_CTX *from); -// BN_to_montgomery sets |ret| equal to |a| in the Montgomery domain. |a| is -// assumed to be in the range [0, n), where |n| is the Montgomery modulus. It +// BN_to_montgomery sets `ret` equal to `a` in the Montgomery domain. `a` is +// assumed to be in the range [0, n), where `n` is the Montgomery modulus. It // returns one on success or zero on error. OPENSSL_EXPORT int BN_to_montgomery(BIGNUM *ret, const BIGNUM *a, const BN_MONT_CTX *mont, BN_CTX *ctx); -// BN_from_montgomery sets |ret| equal to |a| * R^-1, i.e. translates values out -// of the Montgomery domain. |a| is assumed to be in the range [0, n*R), where -// |n| is the Montgomery modulus. Note n < R, so inputs in the range [0, n*n) +// BN_from_montgomery sets `ret` equal to `a` * R^-1, i.e. translates values out +// of the Montgomery domain. `a` is assumed to be in the range [0, n*R), where +// `n` is the Montgomery modulus. Note n < R, so inputs in the range [0, n*n) // are valid. This function returns one on success or zero on error. OPENSSL_EXPORT int BN_from_montgomery(BIGNUM *ret, const BIGNUM *a, const BN_MONT_CTX *mont, BN_CTX *ctx); -// BN_mod_mul_montgomery set |r| equal to |a| * |b|, in the Montgomery domain. -// Both |a| and |b| must already be in the Montgomery domain (by -// |BN_to_montgomery|). In particular, |a| and |b| are assumed to be in the -// range [0, n), where |n| is the Montgomery modulus. It returns one on success +// BN_mod_mul_montgomery set `r` equal to `a` * `b`, in the Montgomery domain. +// Both `a` and `b` must already be in the Montgomery domain (by +// `BN_to_montgomery`). In particular, `a` and `b` are assumed to be in the +// range [0, n), where `n` is the Montgomery modulus. It returns one on success // or zero on error. OPENSSL_EXPORT int BN_mod_mul_montgomery(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, @@ -797,27 +797,27 @@ // Exponentiation. -// BN_exp sets |r| equal to |a|^{|p|}. It does so with a square-and-multiply +// BN_exp sets `r` equal to `a`^{`p`}. It does so with a square-and-multiply // algorithm that leaks side-channel information. It returns one on success or // zero otherwise. OPENSSL_EXPORT int BN_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx); -// BN_mod_exp sets |r| equal to |a|^{|p|} mod |m|. It does so with the best +// BN_mod_exp sets `r` equal to `a`^{`p`} mod `m`. It does so with the best // algorithm for the values provided. It returns one on success or zero -// otherwise. The |BN_mod_exp_mont_consttime| variant must be used if the +// otherwise. The `BN_mod_exp_mont_consttime` variant must be used if the // exponent is secret. OPENSSL_EXPORT int BN_mod_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx); -// BN_mod_exp_mont behaves like |BN_mod_exp| but treats |a| as secret and -// requires 0 <= |a| < |m|. +// BN_mod_exp_mont behaves like `BN_mod_exp` but treats `a` as secret and +// requires 0 <= `a` < `m`. OPENSSL_EXPORT int BN_mod_exp_mont(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, const BN_MONT_CTX *mont); -// BN_mod_exp_mont_consttime behaves like |BN_mod_exp| but treats |a|, |p|, and -// |m| as secret and requires 0 <= |a| < |m|. +// BN_mod_exp_mont_consttime behaves like `BN_mod_exp` but treats `a`, `p`, and +// `m` as secret and requires 0 <= `a` < `m`. OPENSSL_EXPORT int BN_mod_exp_mont_consttime(BIGNUM *rr, const BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, @@ -826,24 +826,24 @@ // Deprecated functions -// BN_bn2mpi serialises the value of |in| to |out|, using a format that consists +// BN_bn2mpi serialises the value of `in` to `out`, using a format that consists // of the number's length in bytes represented as a 4-byte big-endian number, // and the number itself in big-endian format, where the most significant bit // signals a negative number. (The representation of numbers with the MSB set is -// prefixed with null byte). |out| must have sufficient space available; to -// find the needed amount of space, call the function with |out| set to NULL. +// prefixed with null byte). `out` must have sufficient space available; to +// find the needed amount of space, call the function with `out` set to NULL. OPENSSL_EXPORT size_t BN_bn2mpi(const BIGNUM *in, uint8_t *out); -// BN_mpi2bn parses |len| bytes from |in| and returns the resulting value. The -// bytes at |in| are expected to be in the format emitted by |BN_bn2mpi|. +// BN_mpi2bn parses `len` bytes from `in` and returns the resulting value. The +// bytes at `in` are expected to be in the format emitted by `BN_bn2mpi`. // -// If |out| is NULL then a fresh |BIGNUM| is allocated and returned, otherwise -// |out| is reused and returned. On error, NULL is returned and the error queue +// If `out` is NULL then a fresh `BIGNUM` is allocated and returned, otherwise +// `out` is reused and returned. On error, NULL is returned and the error queue // is updated. OPENSSL_EXPORT BIGNUM *BN_mpi2bn(const uint8_t *in, size_t len, BIGNUM *out); -// BN_mod_exp_mont_word is like |BN_mod_exp_mont| except that the base |a| is -// given as a |BN_ULONG| instead of a |BIGNUM *|. It returns one on success +// BN_mod_exp_mont_word is like `BN_mod_exp_mont` except that the base `a` is +// given as a `BN_ULONG` instead of a `BIGNUM *`. It returns one on success // or zero otherwise. OPENSSL_EXPORT int BN_mod_exp_mont_word(BIGNUM *r, BN_ULONG a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, @@ -856,67 +856,67 @@ const BIGNUM *p2, const BIGNUM *m, BN_CTX *ctx, const BN_MONT_CTX *mont); -// BN_MONT_CTX_new returns a fresh |BN_MONT_CTX| or NULL on allocation failure. -// Use |BN_MONT_CTX_new_for_modulus| instead. +// BN_MONT_CTX_new returns a fresh `BN_MONT_CTX` or NULL on allocation failure. +// Use `BN_MONT_CTX_new_for_modulus` instead. OPENSSL_EXPORT BN_MONT_CTX *BN_MONT_CTX_new(void); -// BN_MONT_CTX_set sets up a Montgomery context given the modulus, |mod|. It -// returns one on success and zero on error. Use |BN_MONT_CTX_new_for_modulus| +// BN_MONT_CTX_set sets up a Montgomery context given the modulus, `mod`. It +// returns one on success and zero on error. Use `BN_MONT_CTX_new_for_modulus` // instead. OPENSSL_EXPORT int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *mod, BN_CTX *ctx); -// BN_bn2binpad behaves like |BN_bn2bin_padded|, but it returns |len| on success +// BN_bn2binpad behaves like `BN_bn2bin_padded`, but it returns `len` on success // and -1 on error. // -// Use |BN_bn2bin_padded| instead. It is |size_t|-clean. +// Use `BN_bn2bin_padded` instead. It is `size_t`-clean. OPENSSL_EXPORT int BN_bn2binpad(const BIGNUM *in, uint8_t *out, int len); -// BN_bn2lebinpad behaves like |BN_bn2le_padded|, but it returns |len| on +// BN_bn2lebinpad behaves like `BN_bn2le_padded`, but it returns `len` on // success and -1 on error. // -// Use |BN_bn2le_padded| instead. It is |size_t|-clean. +// Use `BN_bn2le_padded` instead. It is `size_t`-clean. OPENSSL_EXPORT int BN_bn2lebinpad(const BIGNUM *in, uint8_t *out, int len); -// BN_prime_checks is a deprecated alias for |BN_prime_checks_for_validation|. -// Use |BN_prime_checks_for_generation| or |BN_prime_checks_for_validation| -// instead. (This defaults to the |_for_validation| value in order to be +// BN_prime_checks is a deprecated alias for `BN_prime_checks_for_validation`. +// Use `BN_prime_checks_for_generation` or `BN_prime_checks_for_validation` +// instead. (This defaults to the `_for_validation` value in order to be // conservative.) #define BN_prime_checks BN_prime_checks_for_validation -// BN_secure_new calls |BN_new|. +// BN_secure_new calls `BN_new`. OPENSSL_EXPORT BIGNUM *BN_secure_new(void); -// BN_le2bn calls |BN_lebin2bn|. +// BN_le2bn calls `BN_lebin2bn`. OPENSSL_EXPORT BIGNUM *BN_le2bn(const uint8_t *in, size_t len, BIGNUM *ret); // Private functions struct bignum_st { - // d is a pointer to an array of |width| |BN_BITS2|-bit chunks in + // d is a pointer to an array of `width` `BN_BITS2`-bit chunks in // little-endian order. This stores the absolute value of the number. BN_ULONG *d; - // width is the number of elements of |d| which are valid. This value is not - // necessarily minimal; the most-significant words of |d| may be zero. - // |width| determines a potentially loose upper-bound on the absolute value - // of the |BIGNUM|. + // width is the number of elements of `d` which are valid. This value is not + // necessarily minimal; the most-significant words of `d` may be zero. + // `width` determines a potentially loose upper-bound on the absolute value + // of the `BIGNUM`. // - // Functions taking |BIGNUM| inputs must compute the same answer for all - // possible widths. |bn_minimal_width|, |bn_set_minimal_width|, and other + // Functions taking `BIGNUM` inputs must compute the same answer for all + // possible widths. `bn_minimal_width`, `bn_set_minimal_width`, and other // helpers may be used to recover the minimal width, provided it is not // secret. If it is secret, use a different algorithm. Functions may output - // minimal or non-minimal |BIGNUM|s depending on secrecy requirements, but + // minimal or non-minimal `BIGNUM`s depending on secrecy requirements, but // those which cause widths to unboundedly grow beyond the minimal value // should be documented such. // - // Note this is different from historical |BIGNUM| semantics. + // Note this is different from historical `BIGNUM` semantics. int width; - // dmax is number of elements of |d| which are allocated. + // dmax is number of elements of `d` which are allocated. int dmax; // neg is one if the number if negative and zero otherwise. int neg; - // flags is a bitmask of |BN_FLG_*| values + // flags is a bitmask of `BN_FLG_*` values int flags; }; @@ -924,7 +924,7 @@ #define BN_FLG_MALLOCED 0x01 #define BN_FLG_STATIC_DATA 0x02 -// |BN_FLG_CONSTTIME| has been removed and intentionally omitted so code relying +// `BN_FLG_CONSTTIME` has been removed and intentionally omitted so code relying // on it will not compile. Consumers outside BoringSSL should use the // higher-level cryptographic algorithms exposed by other modules. Consumers // within the library should call the appropriate timing-sensitive algorithm
diff --git a/include/openssl/buf.h b/include/openssl/buf.h index 18ae3a1..338beef 100644 --- a/include/openssl/buf.h +++ b/include/openssl/buf.h
@@ -25,7 +25,7 @@ // 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 @@ // 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);
diff --git a/include/openssl/bytestring.h b/include/openssl/bytestring.h index 50263cb..0cdfaf6 100644 --- a/include/openssl/bytestring.h +++ b/include/openssl/bytestring.h
@@ -54,148 +54,148 @@ #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 @@ #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 @@ 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 @@ 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 @@ 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 @@ 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_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_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 @@ } 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 @@ // 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);
diff --git a/util/update_comment_style.py b/util/update_comment_style.py new file mode 100755 index 0000000..580dc07 --- /dev/null +++ b/util/update_comment_style.py
@@ -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()