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/include/openssl/cast.h b/include/openssl/cast.h index 0c19ead..36bad3b 100644 --- a/include/openssl/cast.h +++ b/include/openssl/cast.h
@@ -43,41 +43,41 @@ int short_key; // Use reduced rounds for short key } CAST_KEY; -// CAST_set_key initializes |key| from |len| bytes of key material starting from -// |data|. CAST-128 keys are between 5 and 16 bytes long. If |len| is greater -// than 16, |data| is truncated and only the first 16 bytes are processed. If -// |len| is less than 5, it is internally zero-padded. +// CAST_set_key initializes `key` from `len` bytes of key material starting from +// `data`. CAST-128 keys are between 5 and 16 bytes long. If `len` is greater +// than 16, `data` is truncated and only the first 16 bytes are processed. If +// `len` is less than 5, it is internally zero-padded. OPENSSL_EXPORT void CAST_set_key(CAST_KEY *key, size_t len, const uint8_t *data); -// CAST_ecb_encrypt encrypts (or decrypts, if |enc| is |CAST_DECRYPT|) a single -// 8-byte block from |in| to |out|, using |key|. +// CAST_ecb_encrypt encrypts (or decrypts, if `enc` is `CAST_DECRYPT`) a single +// 8-byte block from `in` to `out`, using `key`. OPENSSL_EXPORT void CAST_ecb_encrypt(const uint8_t in[CAST_BLOCK], uint8_t out[CAST_BLOCK], const CAST_KEY *key, int enc); -// CAST_encrypt encrypts an 8-byte block from |data| in-place with |key|. An +// CAST_encrypt encrypts an 8-byte block from `data` in-place with `key`. An // 8-byte block is represented in this function as two 32-bit integers, // containing the first and second four bytes in big-endian order. OPENSSL_EXPORT void CAST_encrypt(uint32_t data[2], const CAST_KEY *key); -// CAST_decrypt decrypts an 8-byte block from |data| in-place with |key|. An +// CAST_decrypt decrypts an 8-byte block from `data` in-place with `key`. An // 8-byte block is represented in this function as two 32-bit integers, // containing the first and second four bytes in big-endian order. OPENSSL_EXPORT void CAST_decrypt(uint32_t data[2], const CAST_KEY *key); -// CAST_cbc_encrypt encrypts (or decrypts, if |enc| is |CAST_DECRYPT|) |length| -// bytes from |in| to |out| with CAST-128 in CBC mode. |length| must be a -// multiple of 8. The IV is taken from |iv|. When the function completes, the IV -// for the next block is written to |iv|. +// CAST_cbc_encrypt encrypts (or decrypts, if `enc` is `CAST_DECRYPT`) `length` +// bytes from `in` to `out` with CAST-128 in CBC mode. `length` must be a +// multiple of 8. The IV is taken from `iv`. When the function completes, the IV +// for the next block is written to `iv`. OPENSSL_EXPORT void CAST_cbc_encrypt(const uint8_t *in, uint8_t *out, size_t length, const CAST_KEY *ks, uint8_t iv[8], int enc); -// CAST_cfb64_encrypt encrypts (or decrypts, if |enc| is |CAST_DECRYPT|) -// |length| bytes from |in| to |out| with CAST-128 in CFB-64 mode. |length| must -// be a multiple of 8. On the first call, |*num| should be zero and |ivec| the -// IV. On exit, this function will write state to |ivec| and |*num| to resume an +// CAST_cfb64_encrypt encrypts (or decrypts, if `enc` is `CAST_DECRYPT`) +// `length` bytes from `in` to `out` with CAST-128 in CFB-64 mode. `length` must +// be a multiple of 8. On the first call, `*num` should be zero and `ivec` the +// IV. On exit, this function will write state to `ivec` and `*num` to resume an // encryption or decryption operation if the buffers are not contiguous. OPENSSL_EXPORT void CAST_cfb64_encrypt(const uint8_t *in, uint8_t *out, size_t length, const CAST_KEY *schedule,
diff --git a/include/openssl/chacha.h b/include/openssl/chacha.h index ff9f55e..857bda6 100644 --- a/include/openssl/chacha.h +++ b/include/openssl/chacha.h
@@ -26,9 +26,9 @@ // ChaCha20 is a stream cipher. See https://tools.ietf.org/html/rfc8439. -// CRYPTO_chacha_20 encrypts |in_len| bytes from |in| with the given key and -// nonce and writes the result to |out|. If |in| and |out| alias, they must be -// equal. The initial block counter is specified by |counter|. +// CRYPTO_chacha_20 encrypts `in_len` bytes from `in` with the given key and +// nonce and writes the result to `out`. If `in` and `out` alias, they must be +// equal. The initial block counter is specified by `counter`. // // This function implements a 32-bit block counter as in RFC 8439. On overflow, // the counter wraps. Reusing a key, nonce, and block counter combination is not
diff --git a/include/openssl/cipher.h b/include/openssl/cipher.h index ed2eeab..4003082 100644 --- a/include/openssl/cipher.h +++ b/include/openssl/cipher.h
@@ -27,7 +27,7 @@ // Cipher primitives. // -// The following functions return |EVP_CIPHER| objects that implement the named +// The following functions return `EVP_CIPHER` objects that implement the named // cipher algorithm. OPENSSL_EXPORT const EVP_CIPHER *EVP_rc4(void); @@ -73,54 +73,54 @@ // Cipher context allocation. // -// An |EVP_CIPHER_CTX| represents the state of an encryption or decryption in +// An `EVP_CIPHER_CTX` represents the state of an encryption or decryption in // progress. -// EVP_CIPHER_CTX_init initialises an, already allocated, |EVP_CIPHER_CTX|. +// EVP_CIPHER_CTX_init initialises an, already allocated, `EVP_CIPHER_CTX`. OPENSSL_EXPORT void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *ctx); -// EVP_CIPHER_CTX_new allocates a fresh |EVP_CIPHER_CTX|, calls -// |EVP_CIPHER_CTX_init| and returns it, or NULL on allocation failure. +// EVP_CIPHER_CTX_new allocates a fresh `EVP_CIPHER_CTX`, calls +// `EVP_CIPHER_CTX_init` and returns it, or NULL on allocation failure. OPENSSL_EXPORT EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void); -// EVP_CIPHER_CTX_cleanup frees any memory referenced by |ctx|. It returns +// EVP_CIPHER_CTX_cleanup frees any memory referenced by `ctx`. It returns // one. OPENSSL_EXPORT int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *ctx); -// EVP_CIPHER_CTX_free calls |EVP_CIPHER_CTX_cleanup| on |ctx| and then frees -// |ctx| itself. +// EVP_CIPHER_CTX_free calls `EVP_CIPHER_CTX_cleanup` on `ctx` and then frees +// `ctx` itself. OPENSSL_EXPORT void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx); -// EVP_CIPHER_CTX_copy sets |out| to be a duplicate of the current state of -// |in|. The |out| argument must have been previously initialised. +// EVP_CIPHER_CTX_copy sets `out` to be a duplicate of the current state of +// `in`. The `out` argument must have been previously initialised. OPENSSL_EXPORT int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, const EVP_CIPHER_CTX *in); -// EVP_CIPHER_CTX_reset calls |EVP_CIPHER_CTX_cleanup| followed by -// |EVP_CIPHER_CTX_init| and returns one. +// EVP_CIPHER_CTX_reset calls `EVP_CIPHER_CTX_cleanup` followed by +// `EVP_CIPHER_CTX_init` and returns one. OPENSSL_EXPORT int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx); // Cipher context configuration. -// EVP_CipherInit_ex configures |ctx| for a fresh encryption (or decryption, if -// |enc| is zero) operation using |cipher|. If |ctx| has been previously -// configured with a cipher then |cipher|, |key| and |iv| may be |NULL| and -// |enc| may be -1 to reuse the previous values. The operation will use |key| -// as the key and |iv| as the IV (if any). These should have the correct -// lengths given by |EVP_CIPHER_key_length| and |EVP_CIPHER_iv_length|. It +// EVP_CipherInit_ex configures `ctx` for a fresh encryption (or decryption, if +// `enc` is zero) operation using `cipher`. If `ctx` has been previously +// configured with a cipher then `cipher`, `key` and `iv` may be `NULL` and +// `enc` may be -1 to reuse the previous values. The operation will use `key` +// as the key and `iv` as the IV (if any). These should have the correct +// lengths given by `EVP_CIPHER_key_length` and `EVP_CIPHER_iv_length`. It // returns one on success and zero on error. OPENSSL_EXPORT int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher, ENGINE *engine, const uint8_t *key, const uint8_t *iv, int enc); -// EVP_EncryptInit_ex calls |EVP_CipherInit_ex| with |enc| equal to one. +// EVP_EncryptInit_ex calls `EVP_CipherInit_ex` with `enc` equal to one. OPENSSL_EXPORT int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher, ENGINE *impl, const uint8_t *key, const uint8_t *iv); -// EVP_DecryptInit_ex calls |EVP_CipherInit_ex| with |enc| equal to zero. +// EVP_DecryptInit_ex calls `EVP_CipherInit_ex` with `enc` equal to zero. OPENSSL_EXPORT int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher, ENGINE *impl, const uint8_t *key, const uint8_t *iv); @@ -128,29 +128,29 @@ // Cipher operations. -// EVP_EncryptUpdate_ex encrypts |in_len| bytes from |in| and writes up to -// |max_out| bytes of ciphertext to |out|. On success, it sets |*out_len| to +// EVP_EncryptUpdate_ex encrypts `in_len` bytes from `in` and writes up to +// `max_out` bytes of ciphertext to `out`. On success, it sets `*out_len` to // the number of output bytes and returns one. Otherwise, it returns zero. // -// If |max_out| is not large enough for the output, the function will return +// If `max_out` is not large enough for the output, the function will return // zero. The size of output buffer needed depends on the cipher and the number -// of bytes encrypted by |ctx| thus far. +// of bytes encrypted by `ctx` thus far. // // In ciphers whose block size is not 1, such as CBC, individual calls to -// |EVP_EncryptUpdate_ex| may output more or less than |in_len| bytes: a single -// call to |EVP_EncryptUpdate_ex| may output at most |in_len + block_size - 1| -// bytes. Additionally, the total output across all |EVP_EncryptUpdate_ex| and -// |EVP_EncryptFinal_ex2| calls will be at most the total input plus one byte, +// `EVP_EncryptUpdate_ex` may output more or less than `in_len` bytes: a single +// call to `EVP_EncryptUpdate_ex` may output at most `in_len + block_size - 1` +// bytes. Additionally, the total output across all `EVP_EncryptUpdate_ex` and +// `EVP_EncryptFinal_ex2` calls will be at most the total input plus one byte, // rounded up to a multiple of the block size. OPENSSL_EXPORT int EVP_EncryptUpdate_ex(EVP_CIPHER_CTX *ctx, uint8_t *out, size_t *out_len, size_t max_out_len, const uint8_t *in, size_t in_len); // EVP_EncryptFinal_ex2 finishes an encryption operation and writes up to -// |max_out| bytes of output to out. On success, it sets |*out_len| to the +// `max_out` bytes of output to out. On success, it sets `*out_len` to the // number of bytes written and returns one. Otherwise, it returns zero. // -// If |max_out| is not large enough for the output, the function will return +// If `max_out` is not large enough for the output, the function will return // zero. The size of output buffer needed depends on the cipher and the number // of bytes encrypted. // @@ -159,38 +159,38 @@ // // If padding is enabled (the default) and the block size is not 1, then // standard padding is applied to create the final block. If padding is -// disabled (with |EVP_CIPHER_CTX_set_padding|) then any partial block +// disabled (with `EVP_CIPHER_CTX_set_padding`) then any partial block // remaining will cause an error. The function returns one on success and zero // otherwise. OPENSSL_EXPORT int EVP_EncryptFinal_ex2(EVP_CIPHER_CTX *ctx, uint8_t *out, size_t *out_len, size_t max_out_len); -// EVP_DecryptUpdate_ex decrypts |in_len| bytes from |in| and writes up to -// |max_out| bytes of plaintext to |out|. On success, it sets |*out_len| to +// EVP_DecryptUpdate_ex decrypts `in_len` bytes from `in` and writes up to +// `max_out` bytes of plaintext to `out`. On success, it sets `*out_len` to // the number of output bytes and returns one. Otherwise, it returns zero. // -// If |max_out| is not large enough for the output, the function will return +// If `max_out` is not large enough for the output, the function will return // zero. The size of output buffer needed depends on the cipher and the number -// of bytes decrypted by |ctx| thus far. +// of bytes decrypted by `ctx` thus far. // // In ciphers whose block size is not 1, such as CBC, individual calls to -// |EVP_DecryptUpdate_ex| may output more or less than |in_len| bytes: a single -// call to |EVP_DecryptUpdate_ex| may output at most |in_len + block_size - 1| -// bytes. Additionally, the total output across all |EVP_DecryptUpdate_ex| and -// |EVP_DecryptFinal_ex2| calls will be at most the total input. +// `EVP_DecryptUpdate_ex` may output more or less than `in_len` bytes: a single +// call to `EVP_DecryptUpdate_ex` may output at most `in_len + block_size - 1` +// bytes. Additionally, the total output across all `EVP_DecryptUpdate_ex` and +// `EVP_DecryptFinal_ex2` calls will be at most the total input. // // WARNING: if the cipher is an AEAD cipher, decrypted data should not be // parsed or otherwise processed until success has been returned by -// |EVP_EncryptFinal_ex2|. +// `EVP_EncryptFinal_ex2`. OPENSSL_EXPORT int EVP_DecryptUpdate_ex(EVP_CIPHER_CTX *ctx, uint8_t *out, size_t *out_len, size_t max_out_len, const uint8_t *in, size_t in_len); // EVP_DecryptFinal_ex2 finishes a decryption operation and writes up to -// |max_out| bytes of output to out. On success, it sets |*out_len| to the +// `max_out` bytes of output to out. On success, it sets `*out_len` to the // number of bytes written and returns one. Otherwise, it returns zero. // -// If |max_out| is not large enough for the output, the function will return +// If `max_out` is not large enough for the output, the function will return // zero. The size of output buffer needed depends on the cipher and the number // of bytes decrypted. // @@ -206,83 +206,83 @@ OPENSSL_EXPORT int EVP_DecryptFinal_ex2(EVP_CIPHER_CTX *ctx, uint8_t *out, size_t *out_len, size_t max_out_len); -// EVP_CipherUpdate_ex calls either |EVP_EncryptUpdate_ex| or -// |EVP_DecryptUpdate_ex| depending on how |ctx| has been setup. +// EVP_CipherUpdate_ex calls either `EVP_EncryptUpdate_ex` or +// `EVP_DecryptUpdate_ex` depending on how `ctx` has been setup. OPENSSL_EXPORT int EVP_CipherUpdate_ex(EVP_CIPHER_CTX *ctx, uint8_t *out, size_t *out_len, size_t max_out_len, const uint8_t *in, size_t in_len); -// EVP_CipherUpdateAAD adds |in_len| bytes from |in| to the AAD. The AAD must +// EVP_CipherUpdateAAD adds `in_len` bytes from `in` to the AAD. The AAD must // be fully specified in this way before any plaintext or ciphertext is -// supplied to the other functions. Please consider moving to the |EVP_AEAD| +// supplied to the other functions. Please consider moving to the `EVP_AEAD` // APIs instead. OPENSSL_EXPORT int EVP_CipherUpdateAAD(EVP_CIPHER_CTX *ctx, const uint8_t *in, size_t in_len); -// EVP_CipherFinal_ex2 calls either |EVP_EncryptFinal_ex2| or -// |EVP_DecryptFinal_ex2| depending on how |ctx| has been setup. +// EVP_CipherFinal_ex2 calls either `EVP_EncryptFinal_ex2` or +// `EVP_DecryptFinal_ex2` depending on how `ctx` has been setup. OPENSSL_EXPORT int EVP_CipherFinal_ex2(EVP_CIPHER_CTX *ctx, uint8_t *out, size_t *out_len, size_t max_out_len); // Cipher context accessors. -// EVP_CIPHER_CTX_cipher returns the |EVP_CIPHER| underlying |ctx|, or NULL if +// EVP_CIPHER_CTX_cipher returns the `EVP_CIPHER` underlying `ctx`, or NULL if // none has been set. OPENSSL_EXPORT const EVP_CIPHER *EVP_CIPHER_CTX_cipher( const EVP_CIPHER_CTX *ctx); -// EVP_CIPHER_CTX_nid returns a NID identifying the |EVP_CIPHER| underlying -// |ctx| (e.g. |NID_aes_128_gcm|). It will crash if no cipher has been +// EVP_CIPHER_CTX_nid returns a NID identifying the `EVP_CIPHER` underlying +// `ctx` (e.g. `NID_aes_128_gcm`). It will crash if no cipher has been // configured. OPENSSL_EXPORT int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx); -// EVP_CIPHER_CTX_encrypting returns one if |ctx| is configured for encryption +// EVP_CIPHER_CTX_encrypting returns one if `ctx` is configured for encryption // and zero otherwise. OPENSSL_EXPORT int EVP_CIPHER_CTX_encrypting(const EVP_CIPHER_CTX *ctx); // EVP_CIPHER_CTX_block_size returns the block size, in bytes, of the cipher -// underlying |ctx|, or one if the cipher is a stream cipher. It will crash if +// underlying `ctx`, or one if the cipher is a stream cipher. It will crash if // no cipher has been configured. OPENSSL_EXPORT unsigned EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx); // EVP_CIPHER_CTX_key_length returns the key size, in bytes, of the cipher -// underlying |ctx| or zero if no cipher has been configured. +// underlying `ctx` or zero if no cipher has been configured. OPENSSL_EXPORT unsigned EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx); // EVP_CIPHER_CTX_iv_length returns the IV size, in bytes, of the cipher -// underlying |ctx|. It will crash if no cipher has been configured. +// underlying `ctx`. It will crash if no cipher has been configured. OPENSSL_EXPORT unsigned EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx); // EVP_CIPHER_CTX_get_app_data returns the opaque, application data pointer for -// |ctx|, or NULL if none has been set. +// `ctx`, or NULL if none has been set. OPENSSL_EXPORT void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); // EVP_CIPHER_CTX_set_app_data sets the opaque, application data pointer for -// |ctx| to |data|. +// `ctx` to `data`. OPENSSL_EXPORT void EVP_CIPHER_CTX_set_app_data(EVP_CIPHER_CTX *ctx, void *data); // EVP_CIPHER_CTX_flags returns a value which is the OR of zero or more -// |EVP_CIPH_*| flags. It will crash if no cipher has been configured. +// `EVP_CIPH_*` flags. It will crash if no cipher has been configured. OPENSSL_EXPORT uint32_t EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx); -// EVP_CIPHER_CTX_mode returns one of the |EVP_CIPH_*| cipher mode values +// EVP_CIPHER_CTX_mode returns one of the `EVP_CIPH_*` cipher mode values // enumerated below. It will crash if no cipher has been configured. OPENSSL_EXPORT uint32_t EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx); -// EVP_CIPHER_CTX_ctrl is an |ioctl| like function. The |command| argument -// should be one of the |EVP_CTRL_*| values. The |arg| and |ptr| arguments are +// EVP_CIPHER_CTX_ctrl is an `ioctl` like function. The `command` argument +// should be one of the `EVP_CTRL_*` values. The `arg` and `ptr` arguments are // specific to the command in question. OPENSSL_EXPORT int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int command, int arg, void *ptr); -// EVP_CIPHER_CTX_set_padding sets whether padding is enabled for |ctx| and -// returns one. Pass a non-zero |pad| to enable padding (the default) or zero +// EVP_CIPHER_CTX_set_padding sets whether padding is enabled for `ctx` and +// returns one. Pass a non-zero `pad` to enable padding (the default) or zero // to disable. OPENSSL_EXPORT int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *ctx, int pad); -// EVP_CIPHER_CTX_set_key_length sets the key length for |ctx|. This is only +// EVP_CIPHER_CTX_set_key_length sets the key length for `ctx`. This is only // valid for ciphers that can take a variable length key. It returns one on // success and zero on error. OPENSSL_EXPORT int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *ctx, @@ -291,26 +291,26 @@ // Cipher accessors. -// EVP_CIPHER_nid returns a NID identifying |cipher|. (For example, -// |NID_aes_128_gcm|.) +// EVP_CIPHER_nid returns a NID identifying `cipher`. (For example, +// `NID_aes_128_gcm`.) OPENSSL_EXPORT int EVP_CIPHER_nid(const EVP_CIPHER *cipher); -// EVP_CIPHER_block_size returns the block size, in bytes, for |cipher|, or one -// if |cipher| is a stream cipher. +// EVP_CIPHER_block_size returns the block size, in bytes, for `cipher`, or one +// if `cipher` is a stream cipher. OPENSSL_EXPORT unsigned EVP_CIPHER_block_size(const EVP_CIPHER *cipher); -// EVP_CIPHER_key_length returns the key size, in bytes, for |cipher|. If -// |cipher| can take a variable key length then this function returns the -// default key length and |EVP_CIPHER_flags| will return a value with -// |EVP_CIPH_VARIABLE_LENGTH| set. +// EVP_CIPHER_key_length returns the key size, in bytes, for `cipher`. If +// `cipher` can take a variable key length then this function returns the +// default key length and `EVP_CIPHER_flags` will return a value with +// `EVP_CIPH_VARIABLE_LENGTH` set. OPENSSL_EXPORT unsigned EVP_CIPHER_key_length(const EVP_CIPHER *cipher); -// EVP_CIPHER_iv_length returns the IV size, in bytes, of |cipher|, or zero if -// |cipher| doesn't take an IV. +// EVP_CIPHER_iv_length returns the IV size, in bytes, of `cipher`, or zero if +// `cipher` doesn't take an IV. OPENSSL_EXPORT unsigned EVP_CIPHER_iv_length(const EVP_CIPHER *cipher); // EVP_CIPHER_flags returns a value which is the OR of zero or more -// |EVP_CIPH_*| flags. +// `EVP_CIPH_*` flags. OPENSSL_EXPORT uint32_t EVP_CIPHER_flags(const EVP_CIPHER *cipher); // EVP_CIPHER_mode returns one of the cipher mode values enumerated below. @@ -319,31 +319,31 @@ // Key derivation. -// EVP_BytesToKey generates a key and IV for the cipher |type| by iterating -// |md| |count| times using |data| and an optional |salt|, writing the result to -// |key| and |iv|. If not NULL, the |key| and |iv| buffers must have enough -// space to hold a key and IV for |type|, as returned by |EVP_CIPHER_key_length| -// and |EVP_CIPHER_iv_length|. This function returns the length of the key +// EVP_BytesToKey generates a key and IV for the cipher `type` by iterating +// `md` `count` times using `data` and an optional `salt`, writing the result to +// `key` and `iv`. If not NULL, the `key` and `iv` buffers must have enough +// space to hold a key and IV for `type`, as returned by `EVP_CIPHER_key_length` +// and `EVP_CIPHER_iv_length`. This function returns the length of the key // (without the IV) on success or zero on error. // -// If |salt| is NULL, the empty string is used as the salt. Salt lengths other -// than 0 and 8 are not supported by this function. Either of |key| or |iv| may +// If `salt` is NULL, the empty string is used as the salt. Salt lengths other +// than 0 and 8 are not supported by this function. Either of `key` or `iv` may // be NULL to skip that output. // -// When the total data derived is less than the size of |md|, this function +// When the total data derived is less than the size of `md`, this function // implements PBKDF1 from RFC 8018. Otherwise, it generalizes PBKDF1 by -// computing prepending the previous output to |data| and re-running PBKDF1 for +// computing prepending the previous output to `data` and re-running PBKDF1 for // further output. // // This function is provided for compatibility with legacy uses of PBKDF1. New -// applications should use a more modern algorithm, such as |EVP_PBE_scrypt|. +// applications should use a more modern algorithm, such as `EVP_PBE_scrypt`. OPENSSL_EXPORT int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md, const uint8_t salt[8], const uint8_t *data, size_t data_len, unsigned count, uint8_t *key, uint8_t *iv); -// Cipher modes (for |EVP_CIPHER_mode|). +// Cipher modes (for `EVP_CIPHER_mode`). #define EVP_CIPH_STREAM_CIPHER 0x0 #define EVP_CIPH_ECB_MODE 0x1 @@ -354,30 +354,30 @@ #define EVP_CIPH_GCM_MODE 0x6 #define EVP_CIPH_XTS_MODE 0x7 -// The following values are never returned from |EVP_CIPHER_mode| and are +// The following values are never returned from `EVP_CIPHER_mode` and are // included only to make it easier to compile code with BoringSSL. #define EVP_CIPH_CCM_MODE 0x8 #define EVP_CIPH_OCB_MODE 0x9 #define EVP_CIPH_WRAP_MODE 0xa -// Cipher flags (for |EVP_CIPHER_flags|). +// Cipher flags (for `EVP_CIPHER_flags`). // EVP_CIPH_VARIABLE_LENGTH indicates that the cipher takes a variable length // key. #define EVP_CIPH_VARIABLE_LENGTH 0x40 -// EVP_CIPH_ALWAYS_CALL_INIT indicates that the |init| function for the cipher +// EVP_CIPH_ALWAYS_CALL_INIT indicates that the `init` function for the cipher // should always be called when initialising a new operation, even if the key // is NULL to indicate that the same key is being used. #define EVP_CIPH_ALWAYS_CALL_INIT 0x80 // EVP_CIPH_CUSTOM_IV indicates that the cipher manages the IV itself rather -// than keeping it in the |iv| member of |EVP_CIPHER_CTX|. +// than keeping it in the `iv` member of `EVP_CIPHER_CTX`. #define EVP_CIPH_CUSTOM_IV 0x100 // EVP_CIPH_CTRL_INIT indicates that EVP_CTRL_INIT should be used when -// initialising an |EVP_CIPHER_CTX|. +// initialising an `EVP_CIPHER_CTX`. #define EVP_CIPH_CTRL_INIT 0x200 // EVP_CIPH_FLAG_CUSTOM_CIPHER indicates that the cipher manages blocking @@ -389,8 +389,8 @@ // one. #define EVP_CIPH_FLAG_AEAD_CIPHER 0x800 -// EVP_CIPH_CUSTOM_COPY indicates that the |ctrl| callback should be called -// with |EVP_CTRL_COPY| at the end of normal |EVP_CIPHER_CTX_copy| +// EVP_CIPH_CUSTOM_COPY indicates that the `ctrl` callback should be called +// with `EVP_CTRL_COPY` at the end of normal `EVP_CIPHER_CTX_copy` // processing. #define EVP_CIPH_CUSTOM_COPY 0x1000 @@ -403,114 +403,114 @@ // Deprecated functions -// EVP_CipherInit acts like EVP_CipherInit_ex except that |EVP_CIPHER_CTX_init| -// is called on |cipher| first, if |cipher| is not NULL. +// EVP_CipherInit acts like EVP_CipherInit_ex except that `EVP_CIPHER_CTX_init` +// is called on `cipher` first, if `cipher` is not NULL. OPENSSL_EXPORT int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher, const uint8_t *key, const uint8_t *iv, int enc); -// EVP_EncryptInit calls |EVP_CipherInit| with |enc| equal to one. +// EVP_EncryptInit calls `EVP_CipherInit` with `enc` equal to one. OPENSSL_EXPORT int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher, const uint8_t *key, const uint8_t *iv); -// EVP_DecryptInit calls |EVP_CipherInit| with |enc| equal to zero. +// EVP_DecryptInit calls `EVP_CipherInit` with `enc` equal to zero. OPENSSL_EXPORT int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher, const uint8_t *key, const uint8_t *iv); -// EVP_CipherUpdate does the same as |EVP_CipherUpdate_ex|, except that no +// EVP_CipherUpdate does the same as `EVP_CipherUpdate_ex`, except that no // output size is given and thus no bounds checking is performed. // -// Additionally, if |ctx| is an AEAD cipher, e.g. |EVP_aes_128_gcm|, and |out| -// is NULL, this function instead behaves like |EVP_CipherUpdateAAD|. +// Additionally, if `ctx` is an AEAD cipher, e.g. `EVP_aes_128_gcm`, and `out` +// is NULL, this function instead behaves like `EVP_CipherUpdateAAD`. // -// WARNING: This function does not check bounds on |out|, and correctly sizing -// the output buffer is difficult. Use |EVP_CipherUpdate_ex| or -// |EVP_CipherUpdateAAD| instead. +// WARNING: This function does not check bounds on `out`, and correctly sizing +// the output buffer is difficult. Use `EVP_CipherUpdate_ex` or +// `EVP_CipherUpdateAAD` instead. OPENSSL_EXPORT int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out, int *out_len, const uint8_t *in, int in_len); -// EVP_EncryptUpdate does the same as |EVP_EncryptUpdate_ex|, except that no +// EVP_EncryptUpdate does the same as `EVP_EncryptUpdate_ex`, except that no // output size is given and thus no bounds checking is performed. // -// Additionally, if |ctx| is an AEAD cipher, e.g. |EVP_aes_128_gcm|, and |out| -// is NULL, this function instead behaves like |EVP_CipherUpdateAAD|. +// Additionally, if `ctx` is an AEAD cipher, e.g. `EVP_aes_128_gcm`, and `out` +// is NULL, this function instead behaves like `EVP_CipherUpdateAAD`. // -// WARNING: This function does not check bounds on |out|, and correctly sizing -// the output buffer is difficult. Use |EVP_EncryptUpdate_ex| or -// |EVP_CipherUpdateAAD| instead. +// WARNING: This function does not check bounds on `out`, and correctly sizing +// the output buffer is difficult. Use `EVP_EncryptUpdate_ex` or +// `EVP_CipherUpdateAAD` instead. OPENSSL_EXPORT int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out, int *out_len, const uint8_t *in, int in_len); -// EVP_DecryptUpdate does the same as |EVP_DecryptUpdate_ex|, except that no +// EVP_DecryptUpdate does the same as `EVP_DecryptUpdate_ex`, except that no // output size is given and thus no bounds checking is performed. // -// Additionally, if |ctx| is an AEAD cipher, e.g. |EVP_aes_128_gcm|, and |out| -// is NULL, this function instead behaves like |EVP_CipherUpdateAAD|. +// Additionally, if `ctx` is an AEAD cipher, e.g. `EVP_aes_128_gcm`, and `out` +// is NULL, this function instead behaves like `EVP_CipherUpdateAAD`. // // WARNING: This function does not check bounds on out, and correctly sizing -// the output buffer is difficult. Use |EVP_DecryptUpdate_ex| or -// |EVP_CipherUpdateAAD| instead. +// the output buffer is difficult. Use `EVP_DecryptUpdate_ex` or +// `EVP_CipherUpdateAAD` instead. OPENSSL_EXPORT int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out, int *out_len, const uint8_t *in, int in_len); -// EVP_CipherFinal calls |EVP_CipherFinal_ex|. +// EVP_CipherFinal calls `EVP_CipherFinal_ex`. OPENSSL_EXPORT int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, uint8_t *out, int *out_len); -// EVP_CipherFinal_ex does the same as |EVP_CipherFinal_ex2|, except that no +// EVP_CipherFinal_ex does the same as `EVP_CipherFinal_ex2`, except that no // output size is given and thus no bounds checking is performed. // // WARNING: This function does not check bounds on out, and correctly sizing -// the output buffer is difficult. Use |EVP_CipherFinal_ex2| instead. +// the output buffer is difficult. Use `EVP_CipherFinal_ex2` instead. OPENSSL_EXPORT int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, uint8_t *out, int *out_len); -// EVP_EncryptFinal calls |EVP_EncryptFinal_ex|. +// EVP_EncryptFinal calls `EVP_EncryptFinal_ex`. OPENSSL_EXPORT int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, uint8_t *out, int *out_len); -// EVP_EncryptFinal_ex does the same as |EVP_EncryptFinal_ex2|, except that no +// EVP_EncryptFinal_ex does the same as `EVP_EncryptFinal_ex2`, except that no // output size is given and thus no bounds checking is performed. // // WARNING: This function does not check bounds on out, and correctly sizing -// the output buffer is difficult. Use |EVP_EncryptFinal_ex2| instead. +// the output buffer is difficult. Use `EVP_EncryptFinal_ex2` instead. OPENSSL_EXPORT int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, uint8_t *out, int *out_len); -// EVP_DecryptFinal calls |EVP_DecryptFinal_ex|. +// EVP_DecryptFinal calls `EVP_DecryptFinal_ex`. OPENSSL_EXPORT int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, uint8_t *out, int *out_len); -// EVP_DecryptFinal_ex does the same as |EVP_DecryptFinal_ex2|, except that no +// EVP_DecryptFinal_ex does the same as `EVP_DecryptFinal_ex2`, except that no // output size is given and thus no bounds checking is performed. // // WARNING: This function does not check bounds on out, and correctly sizing -// the output buffer is difficult. Use |EVP_DecryptFinal_ex2| instead. +// the output buffer is difficult. Use `EVP_DecryptFinal_ex2` instead. OPENSSL_EXPORT int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, uint8_t *out, int *out_len); -// EVP_Cipher historically exposed an internal implementation detail of |ctx| -// and should not be used. Use |EVP_CipherUpdate| and |EVP_CipherFinal_ex| +// EVP_Cipher historically exposed an internal implementation detail of `ctx` +// and should not be used. Use `EVP_CipherUpdate` and `EVP_CipherFinal_ex` // instead. // -// If |ctx|'s cipher does not have the |EVP_CIPH_FLAG_CUSTOM_CIPHER| flag, it -// encrypts or decrypts |in_len| bytes from |in| and writes the resulting -// |in_len| bytes to |out|. It returns one on success and zero on error. -// |in_len| must be a multiple of the cipher's block size, or the behavior is +// If `ctx`'s cipher does not have the `EVP_CIPH_FLAG_CUSTOM_CIPHER` flag, it +// encrypts or decrypts `in_len` bytes from `in` and writes the resulting +// `in_len` bytes to `out`. It returns one on success and zero on error. +// `in_len` must be a multiple of the cipher's block size, or the behavior is // undefined. // // TODO(davidben): Rather than being undefined (it'll often round the length up // and likely read past the buffer), just fail the operation. // -// If |ctx|'s cipher has the |EVP_CIPH_FLAG_CUSTOM_CIPHER| flag, it runs in one -// of two modes: If |in| is non-NULL, it behaves like |EVP_CipherUpdate|. If -// |in| is NULL, it behaves like |EVP_CipherFinal_ex|. In both cases, it returns -// |*out_len| on success and -1 on error. +// If `ctx`'s cipher has the `EVP_CIPH_FLAG_CUSTOM_CIPHER` flag, it runs in one +// of two modes: If `in` is non-NULL, it behaves like `EVP_CipherUpdate`. If +// `in` is NULL, it behaves like `EVP_CipherFinal_ex`. In both cases, it returns +// `*out_len` on success and -1 on error. // // WARNING: The two possible calling conventions of this function signal errors // incompatibly. In the first, zero indicates an error. In the second, zero @@ -521,20 +521,20 @@ // EVP_add_cipher_alias does nothing and returns one. OPENSSL_EXPORT int EVP_add_cipher_alias(const char *a, const char *b); -// EVP_get_cipherbyname returns an |EVP_CIPHER| given a human readable name in -// |name|, or NULL if the name is unknown. Note using this function links almost +// EVP_get_cipherbyname returns an `EVP_CIPHER` given a human readable name in +// `name`, or NULL if the name is unknown. Note using this function links almost // every cipher implemented by BoringSSL into the binary, not just the ones the // caller requests. Size-conscious callers, such as client software, should not // use this function. OPENSSL_EXPORT const EVP_CIPHER *EVP_get_cipherbyname(const char *name); // These AEADs are deprecated AES-GCM implementations that set -// |EVP_CIPH_FLAG_CUSTOM_CIPHER|. Use |EVP_aead_aes_128_gcm| and -// |EVP_aead_aes_256_gcm| instead. +// `EVP_CIPH_FLAG_CUSTOM_CIPHER`. Use `EVP_aead_aes_128_gcm` and +// `EVP_aead_aes_256_gcm` instead. // // WARNING: Although these APIs allow streaming an individual AES-GCM operation, -// this is not secure. Until calling |EVP_DecryptFinal_ex|, the tag has not yet -// been checked and output released by |EVP_DecryptUpdate| is unauthenticated +// this is not secure. Until calling `EVP_DecryptFinal_ex`, the tag has not yet +// been checked and output released by `EVP_DecryptUpdate` is unauthenticated // and easily manipulated by attackers. Callers must buffer the output and may // not act on it until the entire operation is complete. OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_gcm(void); @@ -547,27 +547,27 @@ OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_gcm(void); OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ofb(void); -// EVP_des_ede3_ecb is an alias for |EVP_des_ede3|. Use the former instead. +// EVP_des_ede3_ecb is an alias for `EVP_des_ede3`. Use the former instead. OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede3_ecb(void); // EVP_aes_128_cfb128 is only available in decrepit. OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_cfb128(void); -// EVP_aes_128_cfb is an alias for |EVP_aes_128_cfb128| and is only available in +// EVP_aes_128_cfb is an alias for `EVP_aes_128_cfb128` and is only available in // decrepit. OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_cfb(void); // EVP_aes_192_cfb128 is only available in decrepit. OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_cfb128(void); -// EVP_aes_192_cfb is an alias for |EVP_aes_192_cfb128| and is only available in +// EVP_aes_192_cfb is an alias for `EVP_aes_192_cfb128` and is only available in // decrepit. OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_cfb(void); // EVP_aes_256_cfb128 is only available in decrepit. OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_cfb128(void); -// EVP_aes_256_cfb is an alias for |EVP_aes_256_cfb128| and is only available in +// EVP_aes_256_cfb is an alias for `EVP_aes_256_cfb128` and is only available in // decrepit. OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_cfb(void); @@ -600,7 +600,7 @@ // EVP_CIPH_NO_PADDING disables padding in block ciphers. #define EVP_CIPH_NO_PADDING 0x800 -// The following are |EVP_CIPHER_CTX_ctrl| commands. +// The following are `EVP_CIPHER_CTX_ctrl` commands. #define EVP_CTRL_INIT 0x0 #define EVP_CTRL_SET_KEY_LENGTH 0x1 #define EVP_CTRL_GET_RC2_KEY_BITS 0x2 @@ -625,7 +625,7 @@ #define EVP_GCM_TLS_EXPLICIT_IV_LEN 8 #define EVP_GCM_TLS_TAG_LEN 16 -// The following are legacy aliases for AEAD |EVP_CIPHER_CTX_ctrl| values. +// The following are legacy aliases for AEAD `EVP_CIPHER_CTX_ctrl` values. #define EVP_CTRL_GCM_SET_IVLEN EVP_CTRL_AEAD_SET_IVLEN #define EVP_CTRL_GCM_GET_TAG EVP_CTRL_AEAD_GET_TAG #define EVP_CTRL_GCM_SET_TAG EVP_CTRL_AEAD_SET_TAG @@ -642,17 +642,17 @@ // app_data is a pointer to opaque, user data. void *app_data; // application stuff - // cipher_data points to the |cipher| specific state. + // cipher_data points to the `cipher` specific state. void *cipher_data; // key_len contains the length of the key, which may differ from - // |cipher->key_len| if the cipher can take a variable key length. + // `cipher->key_len` if the cipher can take a variable key length. unsigned key_len; // encrypt is one if encrypting and zero if decrypting. int encrypt; - // flags contains the OR of zero or more |EVP_CIPH_*| flags, above. + // flags contains the OR of zero or more `EVP_CIPH_*` flags, above. uint32_t flags; // oiv contains the original IV value. @@ -666,14 +666,14 @@ uint8_t buf[EVP_MAX_BLOCK_LENGTH]; // buf_len contains the number of bytes of a partial block contained in - // |buf|. + // `buf`. int buf_len; - // num contains the number of bytes of |iv| which are valid for modes that + // num contains the number of bytes of `iv` which are valid for modes that // manage partial blocks themselves. unsigned num; - // final_used is non-zero if the |final| buffer contains plaintext. + // final_used is non-zero if the `final` buffer contains plaintext. int final_used; uint8_t final[EVP_MAX_BLOCK_LENGTH]; // possible final block
diff --git a/include/openssl/cmac.h b/include/openssl/cmac.h index 3e5a2d6..33bbf58 100644 --- a/include/openssl/cmac.h +++ b/include/openssl/cmac.h
@@ -30,8 +30,8 @@ // One-shot functions. -// AES_CMAC calculates the 16-byte, CMAC authenticator of |in_len| bytes of -// |in| and writes it to |out|. The |key_len| may be 16 or 32 bytes to select +// AES_CMAC calculates the 16-byte, CMAC authenticator of `in_len` bytes of +// `in` and writes it to `out`. The `key_len` may be 16 or 32 bytes to select // between AES-128 and AES-256. It returns one on success or zero on error. OPENSSL_EXPORT int AES_CMAC(uint8_t out[16], const uint8_t *key, size_t key_len, const uint8_t *in, size_t in_len); @@ -39,36 +39,36 @@ // Incremental interface. -// CMAC_CTX_new allocates a fresh |CMAC_CTX| and returns it, or NULL on +// CMAC_CTX_new allocates a fresh `CMAC_CTX` and returns it, or NULL on // error. OPENSSL_EXPORT CMAC_CTX *CMAC_CTX_new(void); -// CMAC_CTX_free frees a |CMAC_CTX|. +// CMAC_CTX_free frees a `CMAC_CTX`. OPENSSL_EXPORT void CMAC_CTX_free(CMAC_CTX *ctx); -// CMAC_CTX_copy sets |out| to be a duplicate of the current state |in|. It +// CMAC_CTX_copy sets `out` to be a duplicate of the current state `in`. It // returns one on success and zero on error. OPENSSL_EXPORT int CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in); -// CMAC_Init configures |ctx| to use the given |key| and |cipher|. The CMAC RFC -// only specifies the use of AES-128 thus |key_len| should be 16 and |cipher| -// should be |EVP_aes_128_cbc()|. However, this implementation also supports -// AES-256 by setting |key_len| to 32 and |cipher| to |EVP_aes_256_cbc()|. The -// |engine| argument is ignored. +// CMAC_Init configures `ctx` to use the given `key` and `cipher`. The CMAC RFC +// only specifies the use of AES-128 thus `key_len` should be 16 and `cipher` +// should be `EVP_aes_128_cbc()`. However, this implementation also supports +// AES-256 by setting `key_len` to 32 and `cipher` to `EVP_aes_256_cbc()`. The +// `engine` argument is ignored. // // It returns one on success or zero on error. OPENSSL_EXPORT int CMAC_Init(CMAC_CTX *ctx, const void *key, size_t key_len, const EVP_CIPHER *cipher, ENGINE *engine); -// CMAC_Reset resets |ctx| so that a fresh message can be authenticated. +// CMAC_Reset resets `ctx` so that a fresh message can be authenticated. OPENSSL_EXPORT int CMAC_Reset(CMAC_CTX *ctx); -// CMAC_Update processes |in_len| bytes of message from |in|. It returns one on +// CMAC_Update processes `in_len` bytes of message from `in`. It returns one on // success or zero on error. OPENSSL_EXPORT int CMAC_Update(CMAC_CTX *ctx, const uint8_t *in, size_t in_len); -// CMAC_Final sets |*out_len| to 16 and, if |out| is not NULL, writes 16 bytes +// CMAC_Final sets `*out_len` to 16 and, if `out` is not NULL, writes 16 bytes // of authenticator to it. It returns one on success or zero on error. OPENSSL_EXPORT int CMAC_Final(CMAC_CTX *ctx, uint8_t *out, size_t *out_len);
diff --git a/include/openssl/cms.h b/include/openssl/cms.h index fdb8e9e..d365a46 100644 --- a/include/openssl/cms.h +++ b/include/openssl/cms.h
@@ -31,10 +31,10 @@ // for S/MIME, is out of scope for BoringSSL. // // As this library is intentionally not a general CMS implementation, BoringSSL -// continues to define |OPENSSL_NO_CMS|, so that most callers turn off their +// continues to define `OPENSSL_NO_CMS`, so that most callers turn off their // general-purpose CMS code. In callers that are compatible with this subset, -// the |BORINGSSL_NO_NO_CMS| build option can be used to suppress -// |OPENSSL_NO_CMS|. +// the `BORINGSSL_NO_NO_CMS` build option can be used to suppress +// `OPENSSL_NO_CMS`. DECLARE_STACK_OF(X509) @@ -51,79 +51,79 @@ #define CMS_USE_KEYID 0x10000 #define CMS_NO_SIGNING_TIME 0x400000 -// CMS_sign returns a newly-allocated |CMS_ContentInfo| structure for building a +// CMS_sign returns a newly-allocated `CMS_ContentInfo` structure for building a // SignedData (RFC 5652), or NULL on error. // -// |certs| must be NULL or zero length. BoringSSL does not support embedding +// `certs` must be NULL or zero length. BoringSSL does not support embedding // certificates in SignedData. // -// |flags| must contain |CMS_DETACHED|, which indicates an external signature. +// `flags` must contain `CMS_DETACHED`, which indicates an external signature. // BoringSSL only supports generating external signatures and does not support // embedding encapsulated content directly in a SignedData. // -// If |pkey| is non-NULL, |CMS_add1_signer| is automatically called with -// |signcert|, |pkey|, a default hash of SHA-256, and |flags|. |flags| will then -// additionally be interpreted as in |CMS_add1_signer|. +// If `pkey` is non-NULL, `CMS_add1_signer` is automatically called with +// `signcert`, `pkey`, a default hash of SHA-256, and `flags`. `flags` will then +// additionally be interpreted as in `CMS_add1_signer`. // -// If |CMS_PARTIAL| or |CMS_STREAM| is set in |flags|, the object will be left -// incomplete. |data| will then be ignored and should be NULL. The caller can -// then continue configuring it and finalizing it with |CMS_final|. Otherwise, -// the object will be finalized with |data| and |flags| passed to |CMS_final|. +// If `CMS_PARTIAL` or `CMS_STREAM` is set in `flags`, the object will be left +// incomplete. `data` will then be ignored and should be NULL. The caller can +// then continue configuring it and finalizing it with `CMS_final`. Otherwise, +// the object will be finalized with `data` and `flags` passed to `CMS_final`. OPENSSL_EXPORT CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, uint32_t flags); -// CMS_ContentInfo_free releases memory associated with |cms|. +// CMS_ContentInfo_free releases memory associated with `cms`. OPENSSL_EXPORT void CMS_ContentInfo_free(CMS_ContentInfo *cms); -// CMS_add1_signer adds a signer to |cms|, which must be a SignedData created by -// |CMS_sign|, with the |CMS_PARTIAL| flag set. The signer will use |signcert|, -// |pkey|, and |md| for the signing certificate, private key, and digest +// CMS_add1_signer adds a signer to `cms`, which must be a SignedData created by +// `CMS_sign`, with the `CMS_PARTIAL` flag set. The signer will use `signcert`, +// `pkey`, and `md` for the signing certificate, private key, and digest // algorithm, respectively. It returns a non-NULL pointer to the signer on -// success, and NULL on error. The signer is owned by |cms| and should not be +// success, and NULL on error. The signer is owned by `cms` and should not be // released by the caller. // -// |flags| is interpreted as follows: +// `flags` is interpreted as follows: // -// - |CMS_PARTIAL| must not be set. BoringSSL does not support configuring a +// - `CMS_PARTIAL` must not be set. BoringSSL does not support configuring a // signer in multiple steps. // -// - |CMS_NOCERTS| must be set. BoringSSL does not support embedding +// - `CMS_NOCERTS` must be set. BoringSSL does not support embedding // certificates in SignedData. // -// - |CMS_NOATTR| must be set. BoringSSL does not support attributes in +// - `CMS_NOATTR` must be set. BoringSSL does not support attributes in // SignedData. // -// - If |CMS_USE_KEYID| is set, SignerInfos will be identified by subject key -// identifier instead of issuer and serial number. |signcert| must then have +// - If `CMS_USE_KEYID` is set, SignerInfos will be identified by subject key +// identifier instead of issuer and serial number. `signcert` must then have // the subject key identifier extension. // -// BoringSSL currently only supports one signer per |CMS_ContentInfo|. +// BoringSSL currently only supports one signer per `CMS_ContentInfo`. // Subsequent calls will fail. Additionally, only RSA keys are currently -// supported for |pkey|. +// supported for `pkey`. OPENSSL_EXPORT CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, uint32_t flags); -// CMS_final finalizes constructing |cms|, which must have been initialized with -// the |CMS_PARTIAL| flag. |data| is read, until EOF, as the data to be +// CMS_final finalizes constructing `cms`, which must have been initialized with +// the `CMS_PARTIAL` flag. `data` is read, until EOF, as the data to be // processed by CMS. It returns one on success and zero on error. // -// |CMS_BINARY| must be set in |flags|. BoringSSL does not support translating +// `CMS_BINARY` must be set in `flags`. BoringSSL does not support translating // inputs according to S/MIME. // -// |dcont| must be NULL. What a non-NULL |dcont| does is not clearly documented +// `dcont` must be NULL. What a non-NULL `dcont` does is not clearly documented // by OpenSSL, and there are no tests to demonstrate its behavior. OPENSSL_EXPORT int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, uint32_t flags); -// i2d_CMS_bio encodes |cms| as a DER-encoded ContentInfo structure (RFC 5652). +// i2d_CMS_bio encodes `cms` as a DER-encoded ContentInfo structure (RFC 5652). // It returns one on success and zero on failure. OPENSSL_EXPORT int i2d_CMS_bio(BIO *out, CMS_ContentInfo *cms); -// i2d_CMS_bio_stream calls |i2d_CMS_bio|. |in| must be NULL and |flags| must -// not contain |CMS_STREAM|. BoringSSL does not support any streaming modes for +// i2d_CMS_bio_stream calls `i2d_CMS_bio`. `in` must be NULL and `flags` must +// not contain `CMS_STREAM`. BoringSSL does not support any streaming modes for // CMS. OPENSSL_EXPORT int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *in, int flags);
diff --git a/include/openssl/conf.h b/include/openssl/conf.h index 875124e..9476577 100644 --- a/include/openssl/conf.h +++ b/include/openssl/conf.h
@@ -36,7 +36,7 @@ // [section_name] // key2=value2 // -// Config files are represented by a |CONF|. Use of this module is strongly +// Config files are represented by a `CONF`. Use of this module is strongly // discouraged. It is a remnant of the OpenSSL command-line tool. Parsing an // untrusted input as a config file risks string injection and denial of service // vulnerabilities. @@ -51,32 +51,32 @@ DEFINE_STACK_OF(CONF_VALUE) -// NCONF_new returns a fresh, empty |CONF|, or NULL on error. The |method| +// NCONF_new returns a fresh, empty `CONF`, or NULL on error. The `method` // argument must be NULL. OPENSSL_EXPORT CONF *NCONF_new(void *method); -// NCONF_free frees all the data owned by |conf| and then |conf| itself. +// NCONF_free frees all the data owned by `conf` and then `conf` itself. OPENSSL_EXPORT void NCONF_free(CONF *conf); -// NCONF_load parses the file named |filename| and adds the values found to -// |conf|. It returns one on success and zero on error. In the event of an -// error, if |out_error_line| is not NULL, |*out_error_line| is set to the +// NCONF_load parses the file named `filename` and adds the values found to +// `conf`. It returns one on success and zero on error. In the event of an +// error, if `out_error_line` is not NULL, `*out_error_line` is set to the // number of the line that contained the error. OPENSSL_EXPORT int NCONF_load(CONF *conf, const char *filename, long *out_error_line); -// NCONF_load_bio acts like |NCONF_load| but reads from |bio| rather than from +// NCONF_load_bio acts like `NCONF_load` but reads from `bio` rather than from // a named file. OPENSSL_EXPORT int NCONF_load_bio(CONF *conf, BIO *bio, long *out_error_line); -// NCONF_get_section returns a stack of values for a given section in |conf|. -// If |section| is NULL, the default section is returned. It returns NULL on +// NCONF_get_section returns a stack of values for a given section in `conf`. +// If `section` is NULL, the default section is returned. It returns NULL on // error. OPENSSL_EXPORT const STACK_OF(CONF_VALUE) *NCONF_get_section( const CONF *conf, const char *section); -// NCONF_get_string returns the value of the key |name|, in section |section|. -// The |section| argument may be NULL to indicate the default section. It +// NCONF_get_string returns the value of the key `name`, in section `section`. +// The `section` argument may be NULL to indicate the default section. It // returns the value or NULL on error. OPENSSL_EXPORT const char *NCONF_get_string(const CONF *conf, const char *section, @@ -91,7 +91,7 @@ #define CONF_MFLAGS_IGNORE_MISSING_FILE 0 // CONF_modules_load_file returns one. BoringSSL is defined to have no config -// file options, thus loading from |filename| always succeeds by doing nothing. +// file options, thus loading from `filename` always succeeds by doing nothing. OPENSSL_EXPORT int CONF_modules_load_file(const char *filename, const char *appname, unsigned long flags);
diff --git a/include/openssl/crypto.h b/include/openssl/crypto.h index a22bfa2..8f6af1f 100644 --- a/include/openssl/crypto.h +++ b/include/openssl/crypto.h
@@ -18,11 +18,11 @@ #include <openssl/base.h> // IWYU pragma: export #include <openssl/sha.h> -// Upstream OpenSSL defines |OPENSSL_malloc|, etc., in crypto.h rather than +// Upstream OpenSSL defines `OPENSSL_malloc`, etc., in crypto.h rather than // mem.h. #include <openssl/mem.h> -// Upstream OpenSSL defines |CRYPTO_LOCK|, etc., in crypto.h rather than +// Upstream OpenSSL defines `CRYPTO_LOCK`, etc., in crypto.h rather than // thread.h. #include <openssl/thread.h> @@ -111,7 +111,7 @@ }; // FIPS_read_counter returns a counter of the number of times the specific -// function denoted by |counter| has been used. This always returns zero unless +// function denoted by `counter` has been used. This always returns zero unless // BoringSSL was built with BORINGSSL_FIPS_COUNTERS defined. OPENSSL_EXPORT size_t FIPS_read_counter(enum fips_counter_t counter); @@ -129,7 +129,7 @@ #define OPENSSL_DIR 4 // OpenSSL_version is a compatibility function that returns the string -// "BoringSSL" if |which| is |OPENSSL_VERSION| and placeholder strings +// "BoringSSL" if `which` is `OPENSSL_VERSION` and placeholder strings // otherwise. OPENSSL_EXPORT const char *OpenSSL_version(int which); @@ -139,7 +139,7 @@ #define SSLEAY_PLATFORM OPENSSL_PLATFORM #define SSLEAY_DIR OPENSSL_DIR -// SSLeay_version calls |OpenSSL_version|. +// SSLeay_version calls `OpenSSL_version`. OPENSSL_EXPORT const char *SSLeay_version(int which); // SSLeay is a compatibility function that returns OPENSSL_VERSION_NUMBER from @@ -196,8 +196,8 @@ // OPENSSL_cleanup does nothing. OPENSSL_EXPORT void OPENSSL_cleanup(void); -// FIPS_mode_set returns one if |on| matches whether BoringSSL was built with -// |BORINGSSL_FIPS| and zero otherwise. +// FIPS_mode_set returns one if `on` matches whether BoringSSL was built with +// `BORINGSSL_FIPS` and zero otherwise. OPENSSL_EXPORT int FIPS_mode_set(int on); // FIPS_module_name returns the name of the FIPS module. @@ -210,10 +210,10 @@ // isn't exactly at a verified version. The version, expressed in base 10, will // be a date in the form yyyymmdd. // -// (This format exceeds a |uint32_t| in the year 4294.) +// (This format exceeds a `uint32_t` in the year 4294.) OPENSSL_EXPORT uint32_t FIPS_version(void); -// FIPS_query_algorithm_status returns one if |algorithm| is FIPS validated in +// FIPS_query_algorithm_status returns one if `algorithm` is FIPS validated in // the current BoringSSL and zero otherwise. OPENSSL_EXPORT int FIPS_query_algorithm_status(const char *algorithm);
diff --git a/include/openssl/ctrdrbg.h b/include/openssl/ctrdrbg.h index 849fc82..678b08b 100644 --- a/include/openssl/ctrdrbg.h +++ b/include/openssl/ctrdrbg.h
@@ -53,17 +53,17 @@ #define CTR_DRBG_NONCE_LEN 16 // CTR_DRBG_MAX_GENERATE_LENGTH is the maximum number of bytes that can be -// generated in a single call to |CTR_DRBG_generate|. +// generated in a single call to `CTR_DRBG_generate`. #define CTR_DRBG_MAX_GENERATE_LENGTH 65536 -// CTR_DRBG_new returns an initialized |CTR_DRBG_STATE|, or NULL if either -// allocation failed or if |personalization_len| is invalid. This DRBG will not +// CTR_DRBG_new returns an initialized `CTR_DRBG_STATE`, or NULL if either +// allocation failed or if `personalization_len` is invalid. This DRBG will not // use a derivation function. OPENSSL_EXPORT CTR_DRBG_STATE *CTR_DRBG_new( const uint8_t entropy[CTR_DRBG_ENTROPY_LEN], const uint8_t *personalization, size_t personalization_len); -// CTR_DRBG_new_df returns an initialized |CTR_DRBG_STATE|, or NULL if either +// CTR_DRBG_new_df returns an initialized `CTR_DRBG_STATE`, or NULL if either // allocation failed or if an argument is invalid. This DRBG will use a // derivation function. OPENSSL_EXPORT CTR_DRBG_STATE *CTR_DRBG_new_df( @@ -71,11 +71,11 @@ const uint8_t nonce[CTR_DRBG_NONCE_LEN], const uint8_t *personalization, size_t personalization_len); -// CTR_DRBG_free frees |state| if non-NULL, or else does nothing. +// CTR_DRBG_free frees `state` if non-NULL, or else does nothing. OPENSSL_EXPORT void CTR_DRBG_free(CTR_DRBG_STATE *state); -// CTR_DRBG_reseed reseeds |drbg| given |CTR_DRBG_ENTROPY_LEN| bytes of entropy -// in |entropy| and, optionally, up to |CTR_DRBG_SEED_LEN| bytes of +// CTR_DRBG_reseed reseeds `drbg` given `CTR_DRBG_ENTROPY_LEN` bytes of entropy +// in `entropy` and, optionally, up to `CTR_DRBG_SEED_LEN` bytes of // additional data. It returns one on success or zero on error. OPENSSL_EXPORT int CTR_DRBG_reseed(CTR_DRBG_STATE *drbg, const uint8_t entropy[CTR_DRBG_ENTROPY_LEN], @@ -83,23 +83,23 @@ size_t additional_data_len); // CTR_DRBG_reseed_ex acts like `CTR_DRBG_reseed` but with variable-length -// entropy input, up to |CTR_DRBG_MAX_ENTROPY_LEN|. +// entropy input, up to `CTR_DRBG_MAX_ENTROPY_LEN`. OPENSSL_EXPORT int CTR_DRBG_reseed_ex(CTR_DRBG_STATE *drbg, const uint8_t *entropy, size_t entropy_len, const uint8_t *additional_data, size_t additional_data_len); -// CTR_DRBG_generate processes to up |CTR_DRBG_ENTROPY_LEN| bytes of additional -// data (if any) and then writes |out_len| random bytes to |out|, where -// |out_len| <= |CTR_DRBG_MAX_GENERATE_LENGTH|. It returns one on success or +// CTR_DRBG_generate processes to up `CTR_DRBG_ENTROPY_LEN` bytes of additional +// data (if any) and then writes `out_len` random bytes to `out`, where +// `out_len` <= `CTR_DRBG_MAX_GENERATE_LENGTH`. It returns one on success or // zero on error. OPENSSL_EXPORT int CTR_DRBG_generate(CTR_DRBG_STATE *drbg, uint8_t *out, size_t out_len, const uint8_t *additional_data, size_t additional_data_len); -// CTR_DRBG_clear zeroises the state of |drbg|. +// CTR_DRBG_clear zeroises the state of `drbg`. OPENSSL_EXPORT void CTR_DRBG_clear(CTR_DRBG_STATE *drbg);
diff --git a/include/openssl/curve25519.h b/include/openssl/curve25519.h index 85a08b8..83d7d97 100644 --- a/include/openssl/curve25519.h +++ b/include/openssl/curve25519.h
@@ -37,12 +37,12 @@ #define X25519_PUBLIC_VALUE_LEN 32 #define X25519_SHARED_KEY_LEN 32 -// X25519_keypair sets |out_public_value| and |out_private_key| to a freshly +// X25519_keypair sets `out_public_value` and `out_private_key` to a freshly // generated, public–private key pair. OPENSSL_EXPORT void X25519_keypair(uint8_t out_public_value[32], uint8_t out_private_key[32]); -// X25519 writes a shared key to |out_shared_key| that is calculated from the +// X25519 writes a shared key to `out_shared_key` that is calculated from the // given private key and the peer's public value. It returns one on success and // zero on error. // @@ -53,7 +53,7 @@ const uint8_t peer_public_value[32]); // X25519_public_from_private calculates a Diffie-Hellman public value from the -// given private key and writes it to |out_public_value|. +// given private key and writes it to `out_public_value`. OPENSSL_EXPORT void X25519_public_from_private(uint8_t out_public_value[32], const uint8_t private_key[32]); @@ -72,20 +72,20 @@ #define ED25519_PUBLIC_KEY_LEN 32 #define ED25519_SIGNATURE_LEN 64 -// ED25519_keypair sets |out_public_key| and |out_private_key| to a freshly +// ED25519_keypair sets `out_public_key` and `out_private_key` to a freshly // generated, public–private key pair. OPENSSL_EXPORT void ED25519_keypair(uint8_t out_public_key[32], uint8_t out_private_key[64]); -// ED25519_sign sets |out_sig| to be a signature of |message_len| bytes from -// |message| using |private_key|. It returns one on success or zero on +// ED25519_sign sets `out_sig` to be a signature of `message_len` bytes from +// `message` using `private_key`. It returns one on success or zero on // allocation failure. OPENSSL_EXPORT int ED25519_sign(uint8_t out_sig[64], const uint8_t *message, size_t message_len, const uint8_t private_key[64]); -// ED25519_verify returns one iff |signature| is a valid signature, by -// |public_key| of |message_len| bytes from |message|. It returns zero +// ED25519_verify returns one iff `signature` is a valid signature, by +// `public_key` of `message_len` bytes from `message`. It returns zero // otherwise. OPENSSL_EXPORT int ED25519_verify(const uint8_t *message, size_t message_len, const uint8_t signature[64], @@ -118,12 +118,12 @@ spake2_role_bob, }; -// SPAKE2_CTX_new creates a new |SPAKE2_CTX| (which can only be used for a +// SPAKE2_CTX_new creates a new `SPAKE2_CTX` (which can only be used for a // single execution of the protocol). SPAKE2 requires the symmetry of the two -// parties to be broken which is indicated via |my_role| – each party must pass +// parties to be broken which is indicated via `my_role` – each party must pass // a different value for this argument. // -// The |my_name| and |their_name| arguments allow optional, opaque names to be +// The `my_name` and `their_name` arguments allow optional, opaque names to be // bound into the protocol. For example MAC addresses, hostnames, usernames // etc. These values are not exposed and can avoid context-confusion attacks // when a password is shared between several devices. @@ -132,19 +132,19 @@ const uint8_t *my_name, size_t my_name_len, const uint8_t *their_name, size_t their_name_len); -// SPAKE2_CTX_free frees |ctx| and all the resources that it has allocated. +// SPAKE2_CTX_free frees `ctx` and all the resources that it has allocated. OPENSSL_EXPORT void SPAKE2_CTX_free(SPAKE2_CTX *ctx); // SPAKE2_MAX_MSG_SIZE is the maximum size of a SPAKE2 message. #define SPAKE2_MAX_MSG_SIZE 32 -// SPAKE2_generate_msg generates a SPAKE2 message given |password|, writes -// it to |out| and sets |*out_len| to the number of bytes written. +// SPAKE2_generate_msg generates a SPAKE2 message given `password`, writes +// it to `out` and sets `*out_len` to the number of bytes written. // -// At most |max_out_len| bytes are written to |out| and, in order to ensure -// success, |max_out_len| should be at least |SPAKE2_MAX_MSG_SIZE| bytes. +// At most `max_out_len` bytes are written to `out` and, in order to ensure +// success, `max_out_len` should be at least `SPAKE2_MAX_MSG_SIZE` bytes. // -// This function can only be called once for a given |SPAKE2_CTX|. +// This function can only be called once for a given `SPAKE2_CTX`. // // It returns one on success and zero on error. OPENSSL_EXPORT int SPAKE2_generate_msg(SPAKE2_CTX *ctx, uint8_t *out, @@ -157,8 +157,8 @@ #define SPAKE2_MAX_KEY_SIZE 64 // SPAKE2_process_msg completes the SPAKE2 exchange given the peer's message in -// |their_msg|, writes at most |max_out_key_len| bytes to |out_key| and sets -// |*out_key_len| to the number of bytes written. +// `their_msg`, writes at most `max_out_key_len` bytes to `out_key` and sets +// `*out_key_len` to the number of bytes written. // // The resulting keying material is suitable for: // - Using directly in a key-confirmation step: i.e. each side could @@ -167,13 +167,13 @@ // - Using as input keying material to HKDF to generate a variety of subkeys // for encryption etc. // -// If |max_out_key_key| is smaller than the amount of key material generated +// If `max_out_key_key` is smaller than the amount of key material generated // then the key is silently truncated. If you want to ensure that no truncation -// occurs then |max_out_key| should be at least |SPAKE2_MAX_KEY_SIZE|. +// occurs then `max_out_key` should be at least `SPAKE2_MAX_KEY_SIZE`. // -// You must call |SPAKE2_generate_msg| on a given |SPAKE2_CTX| before calling -// this function. On successful return, |ctx| is complete and calling -// |SPAKE2_CTX_free| is the only acceptable operation on it. +// You must call `SPAKE2_generate_msg` on a given `SPAKE2_CTX` before calling +// this function. On successful return, `ctx` is complete and calling +// `SPAKE2_CTX_free` is the only acceptable operation on it. // // Returns one on success or zero on error. OPENSSL_EXPORT int SPAKE2_process_msg(SPAKE2_CTX *ctx, uint8_t *out_key,
diff --git a/include/openssl/des.h b/include/openssl/des.h index c601391..ce4571f 100644 --- a/include/openssl/des.h +++ b/include/openssl/des.h
@@ -49,32 +49,32 @@ #define DES_CBC_MODE 0 #define DES_PCBC_MODE 1 -// DES_set_key performs a key schedule and initialises |schedule| with |key|. +// DES_set_key performs a key schedule and initialises `schedule` with `key`. OPENSSL_EXPORT void DES_set_key(const DES_cblock *key, DES_key_schedule *schedule); // DES_set_odd_parity sets the parity bits (the least-significant bits in each -// byte) of |key| given the other bits in each byte. +// byte) of `key` given the other bits in each byte. OPENSSL_EXPORT void DES_set_odd_parity(DES_cblock *key); -// DES_ecb_encrypt encrypts (or decrypts, if |is_encrypt| is |DES_DECRYPT|) a -// single DES block (8 bytes) from |in| to |out|, using the key configured in -// |schedule|. +// DES_ecb_encrypt encrypts (or decrypts, if `is_encrypt` is `DES_DECRYPT`) a +// single DES block (8 bytes) from `in` to `out`, using the key configured in +// `schedule`. OPENSSL_EXPORT void DES_ecb_encrypt(const DES_cblock *in, DES_cblock *out, const DES_key_schedule *schedule, int is_encrypt); -// DES_ncbc_encrypt encrypts (or decrypts, if |enc| is |DES_DECRYPT|) |len| -// bytes from |in| to |out| with DES in CBC mode. |len| must be a multiple of 8. -// The IV is taken from |ivec|. When the function completes, the IV for the next -// block is written to |ivec|. +// DES_ncbc_encrypt encrypts (or decrypts, if `enc` is `DES_DECRYPT`) `len` +// bytes from `in` to `out` with DES in CBC mode. `len` must be a multiple of 8. +// The IV is taken from `ivec`. When the function completes, the IV for the next +// block is written to `ivec`. OPENSSL_EXPORT void DES_ncbc_encrypt(const uint8_t *in, uint8_t *out, size_t len, const DES_key_schedule *schedule, DES_cblock *ivec, int enc); -// DES_ecb3_encrypt encrypts (or decrypts, if |enc| is |DES_DECRYPT|) a single -// block (8 bytes) of data from |input| to |output| using 3DES. +// DES_ecb3_encrypt encrypts (or decrypts, if `enc` is `DES_DECRYPT`) a single +// block (8 bytes) of data from `input` to `output` using 3DES. OPENSSL_EXPORT void DES_ecb3_encrypt(const DES_cblock *input, DES_cblock *output, const DES_key_schedule *ks1, @@ -82,11 +82,11 @@ const DES_key_schedule *ks3, int enc); -// DES_ede3_cbc_encrypt encrypts (or decrypts, if |enc| is |DES_DECRYPT|) |len| -// bytes from |in| to |out| with 3DES in CBC mode. 3DES uses three keys, thus -// the function takes three different |DES_key_schedule|s. |len| must be a -// multiple of 8. The IV is taken from |ivec|. When the function completes, the -// IV for the next block is written to |ivec|. +// DES_ede3_cbc_encrypt encrypts (or decrypts, if `enc` is `DES_DECRYPT`) `len` +// bytes from `in` to `out` with 3DES in CBC mode. 3DES uses three keys, thus +// the function takes three different `DES_key_schedule`s. `len` must be a +// multiple of 8. The IV is taken from `ivec`. When the function completes, the +// IV for the next block is written to `ivec`. OPENSSL_EXPORT void DES_ede3_cbc_encrypt(const uint8_t *in, uint8_t *out, size_t len, const DES_key_schedule *ks1, @@ -94,12 +94,12 @@ const DES_key_schedule *ks3, DES_cblock *ivec, int enc); -// DES_ede2_cbc_encrypt encrypts (or decrypts, if |enc| is |DES_DECRYPT|) |len| -// bytes from |in| to |out| with 3DES in CBC mode. With this keying option, the +// DES_ede2_cbc_encrypt encrypts (or decrypts, if `enc` is `DES_DECRYPT`) `len` +// bytes from `in` to `out` with 3DES in CBC mode. With this keying option, the // first and third 3DES keys are identical. Thus, this function takes only two -// different |DES_key_schedule|s. |len| must be a multiple of 8. The IV is taken -// from |ivec|. When the function completes, the IV for the next block is -// written to |ivec|. +// different `DES_key_schedule`s. `len` must be a multiple of 8. The IV is taken +// from `ivec`. When the function completes, the IV for the next block is +// written to `ivec`. OPENSSL_EXPORT void DES_ede2_cbc_encrypt(const uint8_t *in, uint8_t *out, size_t len, const DES_key_schedule *ks1, @@ -109,7 +109,7 @@ // Deprecated functions. -// DES_set_key_unchecked calls |DES_set_key|. +// DES_set_key_unchecked calls `DES_set_key`. OPENSSL_EXPORT void DES_set_key_unchecked(const DES_cblock *key, DES_key_schedule *schedule);
diff --git a/include/openssl/dh.h b/include/openssl/dh.h index acba59f..59e8c9c 100644 --- a/include/openssl/dh.h +++ b/include/openssl/dh.h
@@ -32,21 +32,21 @@ // Allocation and destruction. // -// A |DH| object represents a Diffie-Hellman key or group parameters. A given +// A `DH` object represents a Diffie-Hellman key or group parameters. A given // object may be used concurrently on multiple threads by non-mutating // functions, provided no other thread is concurrently calling a mutating -// function. Unless otherwise documented, functions which take a |const| pointer -// are non-mutating and functions which take a non-|const| pointer are mutating. +// function. Unless otherwise documented, functions which take a `const` pointer +// are non-mutating and functions which take a non-`const` pointer are mutating. // DH_new returns a new, empty DH object or NULL on error. OPENSSL_EXPORT DH *DH_new(void); -// DH_free decrements the reference count of |dh| and frees it if the reference +// DH_free decrements the reference count of `dh` and frees it if the reference // count drops to zero. OPENSSL_EXPORT void DH_free(DH *dh); -// DH_up_ref increments the reference count of |dh| and returns one. It does not -// mutate |dh| for thread-safety purposes and may be used concurrently. +// DH_up_ref increments the reference count of `dh` and returns one. It does not +// mutate `dh` for thread-safety purposes and may be used concurrently. OPENSSL_EXPORT int DH_up_ref(DH *dh); @@ -56,52 +56,52 @@ // modulus, in bits. #define OPENSSL_DH_MAX_MODULUS_BITS 8192 -// DH_bits returns the size of |dh|'s group modulus, in bits. +// DH_bits returns the size of `dh`'s group modulus, in bits. OPENSSL_EXPORT unsigned DH_bits(const DH *dh); // DH_size returns the number of bytes in the DH group's prime. OPENSSL_EXPORT int DH_size(const DH *dh); -// DH_get0_pub_key returns |dh|'s public key. +// DH_get0_pub_key returns `dh`'s public key. OPENSSL_EXPORT const BIGNUM *DH_get0_pub_key(const DH *dh); -// DH_get0_priv_key returns |dh|'s private key, or NULL if |dh| is a public key. +// DH_get0_priv_key returns `dh`'s private key, or NULL if `dh` is a public key. OPENSSL_EXPORT const BIGNUM *DH_get0_priv_key(const DH *dh); -// DH_get0_p returns |dh|'s group modulus. +// DH_get0_p returns `dh`'s group modulus. OPENSSL_EXPORT const BIGNUM *DH_get0_p(const DH *dh); -// DH_get0_q returns the size of |dh|'s subgroup, or NULL if it is unset. +// DH_get0_q returns the size of `dh`'s subgroup, or NULL if it is unset. OPENSSL_EXPORT const BIGNUM *DH_get0_q(const DH *dh); -// DH_get0_g returns |dh|'s group generator. +// DH_get0_g returns `dh`'s group generator. OPENSSL_EXPORT const BIGNUM *DH_get0_g(const DH *dh); -// DH_get0_key sets |*out_pub_key| and |*out_priv_key|, if non-NULL, to |dh|'s -// public and private key, respectively. If |dh| is a public key, the private +// DH_get0_key sets `*out_pub_key` and `*out_priv_key`, if non-NULL, to `dh`'s +// public and private key, respectively. If `dh` is a public key, the private // key will be set to NULL. OPENSSL_EXPORT void DH_get0_key(const DH *dh, const BIGNUM **out_pub_key, const BIGNUM **out_priv_key); -// DH_set0_key sets |dh|'s public and private key to the specified values. If +// DH_set0_key sets `dh`'s public and private key to the specified values. If // NULL, the field is left unchanged. On success, it takes ownership of each // argument and returns one. Otherwise, it returns zero. OPENSSL_EXPORT int DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key); -// DH_get0_pqg sets |*out_p|, |*out_q|, and |*out_g|, if non-NULL, to |dh|'s p, +// DH_get0_pqg sets `*out_p`, `*out_q`, and `*out_g`, if non-NULL, to `dh`'s p, // q, and g parameters, respectively. OPENSSL_EXPORT void DH_get0_pqg(const DH *dh, const BIGNUM **out_p, const BIGNUM **out_q, const BIGNUM **out_g); -// DH_set0_pqg sets |dh|'s p, q, and g parameters to the specified values. If +// DH_set0_pqg sets `dh`'s p, q, and g parameters to the specified values. If // NULL, the field is left unchanged. On success, it takes ownership of each -// argument and returns one. Otherwise, it returns zero. |q| may be NULL, but -// |p| and |g| must either be specified or already configured on |dh|. +// argument and returns one. Otherwise, it returns zero. `q` may be NULL, but +// `p` and `g` must either be specified or already configured on `dh`. OPENSSL_EXPORT int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g); // DH_set_length sets the number of bits to use for the secret exponent when -// calling |DH_generate_key| on |dh| and returns one. If unset, -// |DH_generate_key| will use the bit length of p. +// calling `DH_generate_key` on `dh` and returns one. If unset, +// `DH_generate_key` will use the bit length of p. OPENSSL_EXPORT int DH_set_length(DH *dh, unsigned priv_length); @@ -112,38 +112,38 @@ // of memory. OPENSSL_EXPORT DH *DH_get_rfc7919_2048(void); -// BN_get_rfc3526_prime_1536 sets |*ret| to the 1536-bit MODP group from RFC -// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated +// BN_get_rfc3526_prime_1536 sets `*ret` to the 1536-bit MODP group from RFC +// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated // and returned. It returns NULL on allocation failure. The generator for this // group is 2. OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *ret); -// BN_get_rfc3526_prime_2048 sets |*ret| to the 2048-bit MODP group from RFC -// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated +// BN_get_rfc3526_prime_2048 sets `*ret` to the 2048-bit MODP group from RFC +// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated // and returned. It returns NULL on allocation failure. The generator for this // group is 2. OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *ret); -// BN_get_rfc3526_prime_3072 sets |*ret| to the 3072-bit MODP group from RFC -// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated +// BN_get_rfc3526_prime_3072 sets `*ret` to the 3072-bit MODP group from RFC +// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated // and returned. It returns NULL on allocation failure. The generator for this // group is 2. OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *ret); -// BN_get_rfc3526_prime_4096 sets |*ret| to the 4096-bit MODP group from RFC -// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated +// BN_get_rfc3526_prime_4096 sets `*ret` to the 4096-bit MODP group from RFC +// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated // and returned. It returns NULL on allocation failure. The generator for this // group is 2. OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *ret); -// BN_get_rfc3526_prime_6144 sets |*ret| to the 6144-bit MODP group from RFC -// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated +// BN_get_rfc3526_prime_6144 sets `*ret` to the 6144-bit MODP group from RFC +// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated // and returned. It returns NULL on allocation failure. The generator for this // group is 2. OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *ret); -// BN_get_rfc3526_prime_8192 sets |*ret| to the 8192-bit MODP group from RFC -// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated +// BN_get_rfc3526_prime_8192 sets `*ret` to the 8192-bit MODP group from RFC +// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated // and returned. It returns NULL on allocation failure. The generator for this // group is 2. OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *ret); @@ -155,12 +155,12 @@ #define DH_GENERATOR_5 5 // DH_generate_parameters_ex generates a suitable Diffie-Hellman group with a -// prime that is |prime_bits| long and stores it in |dh|. The generator of the -// group will be |generator|, which should be |DH_GENERATOR_2| unless there's a -// good reason to use a different value. The |cb| argument contains a callback +// prime that is `prime_bits` long and stores it in `dh`. The generator of the +// group will be `generator`, which should be `DH_GENERATOR_2` unless there's a +// good reason to use a different value. The `cb` argument contains a callback // function that will be called during the generation. See the documentation in -// |bn.h| about this. In addition to the callback invocations from |BN|, |cb| -// will also be called with |event| equal to three when the generation is +// `bn.h` about this. In addition to the callback invocations from `BN`, `cb` +// will also be called with `event` equal to three when the generation is // complete. OPENSSL_EXPORT int DH_generate_parameters_ex(DH *dh, int prime_bits, int generator, BN_GENCB *cb); @@ -169,43 +169,43 @@ // Diffie-Hellman operations. // DH_generate_key generates a new, random, private key and stores it in -// |dh|, if |dh| does not already have a private key. Otherwise, it updates -// |dh|'s public key to match the private key. It returns one on success and +// `dh`, if `dh` does not already have a private key. Otherwise, it updates +// `dh`'s public key to match the private key. It returns one on success and // zero on error. OPENSSL_EXPORT int DH_generate_key(DH *dh); -// DH_compute_key_padded calculates the shared key between |dh| and |peers_key| -// and writes it as a big-endian integer into |out|, padded up to |DH_size| -// bytes. It returns the number of bytes written, which is always |DH_size|, or -// a negative number on error. |out| must have |DH_size| bytes of space. +// DH_compute_key_padded calculates the shared key between `dh` and `peers_key` +// and writes it as a big-endian integer into `out`, padded up to `DH_size` +// bytes. It returns the number of bytes written, which is always `DH_size`, or +// a negative number on error. `out` must have `DH_size` bytes of space. // // WARNING: this differs from the usual BoringSSL return-value convention. // -// Note this function differs from |DH_compute_key| in that it preserves leading +// Note this function differs from `DH_compute_key` in that it preserves leading // zeros in the secret. This function is the preferred variant. It matches PKCS // #3 and avoids some side channel attacks. However, the two functions are not // drop-in replacements for each other. Using a different variant than the // application expects will result in sporadic key mismatches. // // Callers that expect a fixed-width secret should use this function over -// |DH_compute_key|. Callers that use either function should migrate to a modern +// `DH_compute_key`. Callers that use either function should migrate to a modern // primitive such as X25519 or ECDH with P-256 instead. // -// This function does not mutate |dh| for thread-safety purposes and may be used +// This function does not mutate `dh` for thread-safety purposes and may be used // concurrently. OPENSSL_EXPORT int DH_compute_key_padded(uint8_t *out, const BIGNUM *peers_key, DH *dh); -// DH_compute_key_hashed calculates the shared key between |dh| and |peers_key| -// and hashes it with the given |digest|. If the hash output is less than -// |max_out_len| bytes then it writes the hash output to |out| and sets -// |*out_len| to the number of bytes written. Otherwise it signals an error. It +// DH_compute_key_hashed calculates the shared key between `dh` and `peers_key` +// and hashes it with the given `digest`. If the hash output is less than +// `max_out_len` bytes then it writes the hash output to `out` and sets +// `*out_len` to the number of bytes written. Otherwise it signals an error. It // returns one on success or zero on error. // // NOTE: this follows the usual BoringSSL return-value convention, but that's -// different from |DH_compute_key| and |DH_compute_key_padded|. +// different from `DH_compute_key` and `DH_compute_key_padded`. // -// This function does not mutate |dh| for thread-safety purposes and may be used +// This function does not mutate `dh` for thread-safety purposes and may be used // concurrently. OPENSSL_EXPORT int DH_compute_key_hashed(DH *dh, uint8_t *out, size_t *out_len, size_t max_out_len, @@ -226,9 +226,9 @@ #define DH_NOT_SUITABLE_GENERATOR DH_CHECK_NOT_SUITABLE_GENERATOR #define DH_UNABLE_TO_CHECK_GENERATOR DH_CHECK_UNABLE_TO_CHECK_GENERATOR -// DH_check checks the suitability of |dh| as a Diffie-Hellman group. and sets -// |DH_CHECK_*| flags in |*out_flags| if it finds any errors. It returns one if -// |*out_flags| was successfully set and zero on error. +// DH_check checks the suitability of `dh` as a Diffie-Hellman group. and sets +// `DH_CHECK_*` flags in `*out_flags` if it finds any errors. It returns one if +// `*out_flags` was successfully set and zero on error. // // Note: these checks may be quite computationally expensive. OPENSSL_EXPORT int DH_check(const DH *dh, int *out_flags); @@ -237,73 +237,73 @@ #define DH_CHECK_PUBKEY_TOO_LARGE 0x2 #define DH_CHECK_PUBKEY_INVALID 0x4 -// DH_check_pub_key checks the suitability of |pub_key| as a public key for the -// DH group in |dh| and sets |DH_CHECK_PUBKEY_*| flags in |*out_flags| if it -// finds any errors. It returns one if |*out_flags| was successfully set and +// DH_check_pub_key checks the suitability of `pub_key` as a public key for the +// DH group in `dh` and sets `DH_CHECK_PUBKEY_*` flags in `*out_flags` if it +// finds any errors. It returns one if `*out_flags` was successfully set and // zero on error. OPENSSL_EXPORT int DH_check_pub_key(const DH *dh, const BIGNUM *pub_key, int *out_flags); -// DHparams_dup allocates a fresh |DH| and copies the parameters from |dh| into -// it. It returns the new |DH| or NULL on error. +// DHparams_dup allocates a fresh `DH` and copies the parameters from `dh` into +// it. It returns the new `DH` or NULL on error. OPENSSL_EXPORT DH *DHparams_dup(const DH *dh); // ASN.1 functions. // DH_parse_parameters decodes a DER-encoded DHParameter structure (PKCS #3) -// from |cbs| and advances |cbs|. It returns a newly-allocated |DH| or NULL on +// from `cbs` and advances `cbs`. It returns a newly-allocated `DH` or NULL on // error. OPENSSL_EXPORT DH *DH_parse_parameters(CBS *cbs); -// DH_marshal_parameters marshals |dh| as a DER-encoded DHParameter structure -// (PKCS #3) and appends the result to |cbb|. It returns one on success and zero +// DH_marshal_parameters marshals `dh` as a DER-encoded DHParameter structure +// (PKCS #3) and appends the result to `cbb`. It returns one on success and zero // on error. OPENSSL_EXPORT int DH_marshal_parameters(CBB *cbb, const DH *dh); // Deprecated functions. -// DH_generate_parameters behaves like |DH_generate_parameters_ex|, which is +// DH_generate_parameters behaves like `DH_generate_parameters_ex`, which is // what you should use instead. It returns NULL on error, or a newly-allocated -// |DH| on success. This function is provided for compatibility only. +// `DH` on success. This function is provided for compatibility only. OPENSSL_EXPORT DH *DH_generate_parameters(int prime_len, int generator, void (*callback)(int, int, void *), void *cb_arg); -// d2i_DHparams parses a DER-encoded DHParameter structure (PKCS #3) from |len| -// bytes at |*inp|, as in |d2i_SAMPLE|. +// d2i_DHparams parses a DER-encoded DHParameter structure (PKCS #3) from `len` +// bytes at `*inp`, as in `d2i_SAMPLE`. // -// Use |DH_parse_parameters| instead. +// Use `DH_parse_parameters` instead. OPENSSL_EXPORT DH *d2i_DHparams(DH **ret, const unsigned char **inp, long len); -// i2d_DHparams marshals |in| to a DER-encoded DHParameter structure (PKCS #3), -// as described in |i2d_SAMPLE|. +// i2d_DHparams marshals `in` to a DER-encoded DHParameter structure (PKCS #3), +// as described in `i2d_SAMPLE`. // -// Use |DH_marshal_parameters| instead. +// Use `DH_marshal_parameters` instead. OPENSSL_EXPORT int i2d_DHparams(const DH *in, unsigned char **outp); -// DH_compute_key behaves like |DH_compute_key_padded| but, contrary to PKCS #3, +// DH_compute_key behaves like `DH_compute_key_padded` but, contrary to PKCS #3, // returns a variable-length shared key with leading zeros. It returns the -// number of bytes written, or a negative number on error. |out| must have -// |DH_size| bytes of space. +// number of bytes written, or a negative number on error. `out` must have +// `DH_size` bytes of space. // // WARNING: this differs from the usual BoringSSL return-value convention. // // Note this function's running time and memory access pattern leaks information -// about the shared secret. Particularly if |dh| is reused, this may result in +// about the shared secret. Particularly if `dh` is reused, this may result in // side channel attacks such as https://raccoon-attack.com/. // -// |DH_compute_key_padded| is the preferred variant and avoids the above +// `DH_compute_key_padded` is the preferred variant and avoids the above // attacks. However, the two functions are not drop-in replacements for each // other. Using a different variant than the application expects will result in // sporadic key mismatches. // -// Callers that expect a fixed-width secret should use |DH_compute_key_padded| +// Callers that expect a fixed-width secret should use `DH_compute_key_padded` // instead. Callers that use either function should migrate to a modern // primitive such as X25519 or ECDH with P-256 instead. // -// This function does not mutate |dh| for thread-safety purposes and may be used +// This function does not mutate `dh` for thread-safety purposes and may be used // concurrently. OPENSSL_EXPORT int DH_compute_key(uint8_t *out, const BIGNUM *peers_key, DH *dh);
diff --git a/include/openssl/digest.h b/include/openssl/digest.h index 62ad573..19e63be 100644 --- a/include/openssl/digest.h +++ b/include/openssl/digest.h
@@ -31,7 +31,7 @@ // Hash algorithms. // -// The following functions return |EVP_MD| objects that implement the named hash +// The following functions return `EVP_MD` objects that implement the named hash // function. OPENSSL_EXPORT const EVP_MD *EVP_md4(void); @@ -44,15 +44,15 @@ OPENSSL_EXPORT const EVP_MD *EVP_sha512_256(void); OPENSSL_EXPORT const EVP_MD *EVP_blake2b256(void); -// EVP_md5_sha1 is a TLS-specific |EVP_MD| which computes the concatenation of +// EVP_md5_sha1 is a TLS-specific `EVP_MD` which computes the concatenation of // MD5 and SHA-1, as used in TLS 1.1 and below. OPENSSL_EXPORT const EVP_MD *EVP_md5_sha1(void); -// EVP_get_digestbynid returns an |EVP_MD| for the given NID, or NULL if no +// EVP_get_digestbynid returns an `EVP_MD` for the given NID, or NULL if no // such digest is known. OPENSSL_EXPORT const EVP_MD *EVP_get_digestbynid(int nid); -// EVP_get_digestbyobj returns an |EVP_MD| for the given |ASN1_OBJECT|, or NULL +// EVP_get_digestbyobj returns an `EVP_MD` for the given `ASN1_OBJECT`, or NULL // if no such digest is known. OPENSSL_EXPORT const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *obj); @@ -62,56 +62,56 @@ // An EVP_MD_CTX represents the state of a specific digest operation in // progress. -// EVP_MD_CTX_init initialises an, already allocated, |EVP_MD_CTX|. This is the +// EVP_MD_CTX_init initialises an, already allocated, `EVP_MD_CTX`. This is the // same as setting the structure to zero. OPENSSL_EXPORT void EVP_MD_CTX_init(EVP_MD_CTX *ctx); -// EVP_MD_CTX_new allocates and initialises a fresh |EVP_MD_CTX| and returns -// it, or NULL on allocation failure. The caller must use |EVP_MD_CTX_free| to +// EVP_MD_CTX_new allocates and initialises a fresh `EVP_MD_CTX` and returns +// it, or NULL on allocation failure. The caller must use `EVP_MD_CTX_free` to // release the resulting object. OPENSSL_EXPORT EVP_MD_CTX *EVP_MD_CTX_new(void); -// EVP_MD_CTX_cleanup frees any resources owned by |ctx| and resets it to a -// freshly initialised state. It does not free |ctx| itself. It returns one. +// EVP_MD_CTX_cleanup frees any resources owned by `ctx` and resets it to a +// freshly initialised state. It does not free `ctx` itself. It returns one. OPENSSL_EXPORT int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx); -// EVP_MD_CTX_cleanse zeros the digest state in |ctx| and then performs the -// actions of |EVP_MD_CTX_cleanup|. Note that some |EVP_MD_CTX| objects contain -// more than just a digest (e.g. those resulting from |EVP_DigestSignInit|) but +// EVP_MD_CTX_cleanse zeros the digest state in `ctx` and then performs the +// actions of `EVP_MD_CTX_cleanup`. Note that some `EVP_MD_CTX` objects contain +// more than just a digest (e.g. those resulting from `EVP_DigestSignInit`) but // this function does not zero out more than just the digest state even in that // case. OPENSSL_EXPORT void EVP_MD_CTX_cleanse(EVP_MD_CTX *ctx); -// EVP_MD_CTX_free calls |EVP_MD_CTX_cleanup| and then frees |ctx| itself. +// EVP_MD_CTX_free calls `EVP_MD_CTX_cleanup` and then frees `ctx` itself. OPENSSL_EXPORT void EVP_MD_CTX_free(EVP_MD_CTX *ctx); -// EVP_MD_CTX_copy_ex sets |out|, which must already be initialised, to be a -// copy of |in|. It returns one on success and zero on allocation failure. +// EVP_MD_CTX_copy_ex sets `out`, which must already be initialised, to be a +// copy of `in`. It returns one on success and zero on allocation failure. OPENSSL_EXPORT int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in); -// EVP_MD_CTX_move sets |out|, which must already be initialised, to the hash -// state in |in|. |in| is mutated and left in an empty state. +// EVP_MD_CTX_move sets `out`, which must already be initialised, to the hash +// state in `in`. `in` is mutated and left in an empty state. OPENSSL_EXPORT void EVP_MD_CTX_move(EVP_MD_CTX *out, EVP_MD_CTX *in); -// EVP_MD_CTX_reset calls |EVP_MD_CTX_cleanup| followed by |EVP_MD_CTX_init|. It +// EVP_MD_CTX_reset calls `EVP_MD_CTX_cleanup` followed by `EVP_MD_CTX_init`. It // returns one. OPENSSL_EXPORT int EVP_MD_CTX_reset(EVP_MD_CTX *ctx); // Digest operations. -// EVP_DigestInit_ex configures |ctx|, which must already have been -// initialised, for a fresh hashing operation using |type|. It returns one on +// EVP_DigestInit_ex configures `ctx`, which must already have been +// initialised, for a fresh hashing operation using `type`. It returns one on // success and zero on allocation failure. OPENSSL_EXPORT int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *engine); -// EVP_DigestInit acts like |EVP_DigestInit_ex| except that |ctx| is +// EVP_DigestInit acts like `EVP_DigestInit_ex` except that `ctx` is // initialised before use. OPENSSL_EXPORT int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); -// EVP_DigestUpdate hashes |len| bytes from |data| into the hashing operation -// in |ctx|. It returns one. +// EVP_DigestUpdate hashes `len` bytes from `data` into the hashing operation +// in `ctx`. It returns one. OPENSSL_EXPORT int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *data, size_t len); @@ -124,24 +124,24 @@ // bytes. #define EVP_MAX_MD_BLOCK_SIZE 128 // SHA-512 is the longest so far. -// EVP_DigestFinal_ex finishes the digest in |ctx| and writes the output to -// |md_out|. |EVP_MD_CTX_size| bytes are written, which is at most -// |EVP_MAX_MD_SIZE|. If |out_size| is not NULL then |*out_size| is set to the +// EVP_DigestFinal_ex finishes the digest in `ctx` and writes the output to +// `md_out`. `EVP_MD_CTX_size` bytes are written, which is at most +// `EVP_MAX_MD_SIZE`. If `out_size` is not NULL then `*out_size` is set to the // number of bytes written. It returns one. After this call, the hash cannot be -// updated or finished again until |EVP_DigestInit_ex| is called to start +// updated or finished again until `EVP_DigestInit_ex` is called to start // another hashing operation. OPENSSL_EXPORT int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, uint8_t *md_out, unsigned int *out_size); -// EVP_DigestFinal acts like |EVP_DigestFinal_ex| except that -// |EVP_MD_CTX_cleanup| is called on |ctx| before returning. +// EVP_DigestFinal acts like `EVP_DigestFinal_ex` except that +// `EVP_MD_CTX_cleanup` is called on `ctx` before returning. OPENSSL_EXPORT int EVP_DigestFinal(EVP_MD_CTX *ctx, uint8_t *md_out, unsigned int *out_size); -// EVP_Digest performs a complete hashing operation in one call. It hashes |len| -// bytes from |data| and writes the digest to |md_out|. |EVP_MD_CTX_size| bytes -// are written, which is at most |EVP_MAX_MD_SIZE|. If |out_size| is not NULL -// then |*out_size| is set to the number of bytes written. It returns one on +// EVP_Digest performs a complete hashing operation in one call. It hashes `len` +// bytes from `data` and writes the digest to `md_out`. `EVP_MD_CTX_size` bytes +// are written, which is at most `EVP_MAX_MD_SIZE`. If `out_size` is not NULL +// then `*out_size` is set to the number of bytes written. It returns one on // success and zero otherwise. OPENSSL_EXPORT int EVP_Digest(const void *data, size_t len, uint8_t *md_out, unsigned int *md_out_size, const EVP_MD *type, @@ -153,17 +153,17 @@ // These functions allow code to learn details about an abstract hash // function. -// EVP_MD_type returns a NID identifying |md|. (For example, |NID_sha256|.) +// EVP_MD_type returns a NID identifying `md`. (For example, `NID_sha256`.) OPENSSL_EXPORT int EVP_MD_type(const EVP_MD *md); -// EVP_MD_flags returns the flags for |md|, which is a set of |EVP_MD_FLAG_*| +// EVP_MD_flags returns the flags for `md`, which is a set of `EVP_MD_FLAG_*` // values, ORed together. OPENSSL_EXPORT uint32_t EVP_MD_flags(const EVP_MD *md); -// EVP_MD_size returns the digest size of |md|, in bytes. +// EVP_MD_size returns the digest size of `md`, in bytes. OPENSSL_EXPORT size_t EVP_MD_size(const EVP_MD *md); -// EVP_MD_block_size returns the native block-size of |md|, in bytes. +// EVP_MD_block_size returns the native block-size of `md`, in bytes. OPENSSL_EXPORT size_t EVP_MD_block_size(const EVP_MD *md); // EVP_MD_FLAG_DIGALGID_ABSENT indicates that the parameter type in an X.509 @@ -173,7 +173,7 @@ // EVP_MD_FLAG_XOF indicates that the digest is an extensible-output function // (XOF). This flag is defined for compatibility and will never be set in any -// |EVP_MD| in BoringSSL. +// `EVP_MD` in BoringSSL. #define EVP_MD_FLAG_XOF 4 @@ -184,26 +184,26 @@ OPENSSL_EXPORT const EVP_MD *EVP_MD_CTX_get0_md(const EVP_MD_CTX *ctx); // EVP_MD_CTX_md returns the underlying digest function, or NULL if one has not -// been set. (This is the same as |EVP_MD_CTX_get0_md| but OpenSSL has +// been set. (This is the same as `EVP_MD_CTX_get0_md` but OpenSSL has // deprecated this spelling.) OPENSSL_EXPORT const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); -// EVP_MD_CTX_size returns the digest size of |ctx|, in bytes. It -// will crash if a digest hasn't been set on |ctx|. +// EVP_MD_CTX_size returns the digest size of `ctx`, in bytes. It +// will crash if a digest hasn't been set on `ctx`. OPENSSL_EXPORT size_t EVP_MD_CTX_size(const EVP_MD_CTX *ctx); // EVP_MD_CTX_block_size returns the block size of the digest function used by -// |ctx|, in bytes. It will crash if a digest hasn't been set on |ctx|. +// `ctx`, in bytes. It will crash if a digest hasn't been set on `ctx`. OPENSSL_EXPORT size_t EVP_MD_CTX_block_size(const EVP_MD_CTX *ctx); -// EVP_MD_CTX_type returns a NID describing the digest function used by |ctx|. -// (For example, |NID_sha256|.) It will crash if a digest hasn't been set on -// |ctx|. +// EVP_MD_CTX_type returns a NID describing the digest function used by `ctx`. +// (For example, `NID_sha256`.) It will crash if a digest hasn't been set on +// `ctx`. OPENSSL_EXPORT int EVP_MD_CTX_type(const EVP_MD_CTX *ctx); -// EVP_MD_CTX_pkey_ctx returns the |EVP_PKEY_CTX| used to configure additional -// parameters on |ctx| if |ctx| is used for a sign or verify operation with -// |EVP_DigestSignInit| or |EVP_DigestVerifyInit|. It returns NULL otherwise. +// EVP_MD_CTX_pkey_ctx returns the `EVP_PKEY_CTX` used to configure additional +// parameters on `ctx` if `ctx` is used for a sign or verify operation with +// `EVP_DigestSignInit` or `EVP_DigestVerifyInit`. It returns NULL otherwise. OPENSSL_EXPORT EVP_PKEY_CTX *EVP_MD_CTX_pkey_ctx(const EVP_MD_CTX *ctx); @@ -214,19 +214,19 @@ // EVP_parse_digest_algorithm parses an AlgorithmIdentifier structure containing // a hash function OID (for example, 2.16.840.1.101.3.4.2.1 is SHA-256) and -// advances |cbs|. The parameters field may either be omitted or a NULL. It +// advances `cbs`. The parameters field may either be omitted or a NULL. It // returns the digest function or NULL on error. OPENSSL_EXPORT const EVP_MD *EVP_parse_digest_algorithm(CBS *cbs); -// EVP_parse_digest_algorithm_nid behaves like |EVP_parse_digest_algorithm| -// except it returns |NID_undef| on error and some other value on success. This +// EVP_parse_digest_algorithm_nid behaves like `EVP_parse_digest_algorithm` +// except it returns `NID_undef` on error and some other value on success. This // may be used to avoid depending on every digest algorithm in the library. OPENSSL_EXPORT int EVP_parse_digest_algorithm_nid(CBS *cbs); -// EVP_marshal_digest_algorithm marshals |md| as an AlgorithmIdentifier -// structure and appends the result to |cbb|. It returns one on success and zero +// EVP_marshal_digest_algorithm marshals `md` as an AlgorithmIdentifier +// structure and appends the result to `cbb`. It returns one on success and zero // on error. It sets the parameters field to NULL. Use -// |EVP_marshal_digest_algorithm_no_params| to omit the parameters instead. +// `EVP_marshal_digest_algorithm_no_params` to omit the parameters instead. // // In general, the parameters should be omitted for digest algorithms, but the // following specifications require a NULL parameter instead. @@ -241,23 +241,23 @@ OPENSSL_EXPORT int EVP_marshal_digest_algorithm(CBB *cbb, const EVP_MD *md); // EVP_marshal_digest_algorithm_no_params behaves like -// |EVP_marshal_digest_algorithm| but omits the parameters field. +// `EVP_marshal_digest_algorithm` but omits the parameters field. OPENSSL_EXPORT int EVP_marshal_digest_algorithm_no_params(CBB *cbb, const EVP_MD *md); // Deprecated functions. -// EVP_MD_CTX_copy sets |out|, which must /not/ be initialised, to be a copy of -// |in|. It returns one on success and zero on error. +// EVP_MD_CTX_copy sets `out`, which must /not/ be initialised, to be a copy of +// `in`. It returns one on success and zero on error. OPENSSL_EXPORT int EVP_MD_CTX_copy(EVP_MD_CTX *out, const EVP_MD_CTX *in); // EVP_add_digest does nothing and returns one. It exists only for // compatibility with OpenSSL. OPENSSL_EXPORT int EVP_add_digest(const EVP_MD *digest); -// EVP_get_digestbyname returns an |EVP_MD| given a human readable name in -// |name|, or NULL if the name is unknown. +// EVP_get_digestbyname returns an `EVP_MD` given a human readable name in +// `name`, or NULL if the name is unknown. OPENSSL_EXPORT const EVP_MD *EVP_get_digestbyname(const char *name); // EVP_dss1 returns the value of EVP_sha1(). This was provided by OpenSSL to @@ -266,10 +266,10 @@ // interface will always fail. OPENSSL_EXPORT const EVP_MD *EVP_dss1(void); -// EVP_MD_CTX_create calls |EVP_MD_CTX_new|. +// EVP_MD_CTX_create calls `EVP_MD_CTX_new`. OPENSSL_EXPORT EVP_MD_CTX *EVP_MD_CTX_create(void); -// EVP_MD_CTX_destroy calls |EVP_MD_CTX_free|. +// EVP_MD_CTX_destroy calls `EVP_MD_CTX_free`. OPENSSL_EXPORT void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx); // EVP_DigestFinalXOF returns zero and adds an error to the error queue. @@ -277,7 +277,7 @@ OPENSSL_EXPORT int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, uint8_t *out, size_t len); -// EVP_MD_meth_get_flags calls |EVP_MD_flags|. +// EVP_MD_meth_get_flags calls `EVP_MD_flags`. OPENSSL_EXPORT uint32_t EVP_MD_meth_get_flags(const EVP_MD *md); // EVP_MD_CTX_set_flags does nothing. @@ -289,23 +289,23 @@ // their needs). Thus this exists only to allow code to compile. #define EVP_MD_CTX_FLAG_NON_FIPS_ALLOW 0 -// EVP_MD_nid calls |EVP_MD_type|. +// EVP_MD_nid calls `EVP_MD_type`. OPENSSL_EXPORT int EVP_MD_nid(const EVP_MD *md); -// EVP_MD_fetch behaves like |EVP_get_digestbyname|. |libctx| and |propq| are -// ignored. Although it returns a non-const pointer, |EVP_MD|s in BoringSSL are +// EVP_MD_fetch behaves like `EVP_get_digestbyname`. `libctx` and `propq` are +// ignored. Although it returns a non-const pointer, `EVP_MD`s in BoringSSL are // static and do not need to be freed. OPENSSL_EXPORT EVP_MD *EVP_MD_fetch(OSSL_LIB_CTX *libctx, const char *name, const char *propq); -// EVP_MD_up_ref returns one. |EVP_MD|s in BoringSSL are static. +// EVP_MD_up_ref returns one. `EVP_MD`s in BoringSSL are static. OPENSSL_EXPORT int EVP_MD_up_ref(EVP_MD *md); -// EVP_MD_free does nothing. |EVP_MD|s in BoringSSL are static. +// EVP_MD_free does nothing. `EVP_MD`s in BoringSSL are static. OPENSSL_EXPORT void EVP_MD_free(EVP_MD *md); -// EVP_Q_digest behaves like |EVP_Digest| but specifies the digest by a string -// |name|. |libctx| and |propq| are ignored. +// EVP_Q_digest behaves like `EVP_Digest` but specifies the digest by a string +// `name`. `libctx` and `propq` are ignored. OPENSSL_EXPORT int EVP_Q_digest(OSSL_LIB_CTX *libctx, const char *name, const char *propq, const void *in, size_t in_len, uint8_t *out, size_t *out_len); @@ -337,7 +337,7 @@ EVP_PKEY_CTX *pctx; // pctx_ops, if not NULL, points to a vtable that contains functions to - // manipulate |pctx|. + // manipulate `pctx`. const struct evp_md_pctx_ops *pctx_ops; } /* EVP_MD_CTX */;
diff --git a/include/openssl/dsa.h b/include/openssl/dsa.h index 9b50286..fff5b76 100644 --- a/include/openssl/dsa.h +++ b/include/openssl/dsa.h
@@ -34,21 +34,21 @@ // Allocation and destruction. // -// A |DSA| object represents a DSA key or group parameters. A given object may +// A `DSA` object represents a DSA key or group parameters. A given object may // be used concurrently on multiple threads by non-mutating functions, provided // no other thread is concurrently calling a mutating function. Unless otherwise -// documented, functions which take a |const| pointer are non-mutating and -// functions which take a non-|const| pointer are mutating. +// documented, functions which take a `const` pointer are non-mutating and +// functions which take a non-`const` pointer are mutating. // DSA_new returns a new, empty DSA object or NULL on error. OPENSSL_EXPORT DSA *DSA_new(void); -// DSA_free decrements the reference count of |dsa| and frees it if the +// DSA_free decrements the reference count of `dsa` and frees it if the // reference count drops to zero. OPENSSL_EXPORT void DSA_free(DSA *dsa); -// DSA_up_ref increments the reference count of |dsa| and returns one. It does -// not mutate |dsa| for thread-safety purposes and may be used concurrently. +// DSA_up_ref increments the reference count of `dsa` and returns one. It does +// not mutate `dsa` for thread-safety purposes and may be used concurrently. OPENSSL_EXPORT int DSA_up_ref(DSA *dsa); @@ -58,49 +58,49 @@ // bits. #define OPENSSL_DSA_MAX_MODULUS_BITS 8192 -// DSA_bits returns the size of |dsa|'s group modulus, in bits. +// DSA_bits returns the size of `dsa`'s group modulus, in bits. OPENSSL_EXPORT unsigned DSA_bits(const DSA *dsa); -// DSA_get0_pub_key returns |dsa|'s public key. +// DSA_get0_pub_key returns `dsa`'s public key. OPENSSL_EXPORT const BIGNUM *DSA_get0_pub_key(const DSA *dsa); -// DSA_get0_priv_key returns |dsa|'s private key, or NULL if |dsa| is a public +// DSA_get0_priv_key returns `dsa`'s private key, or NULL if `dsa` is a public // key. OPENSSL_EXPORT const BIGNUM *DSA_get0_priv_key(const DSA *dsa); -// DSA_get0_p returns |dsa|'s group modulus. +// DSA_get0_p returns `dsa`'s group modulus. OPENSSL_EXPORT const BIGNUM *DSA_get0_p(const DSA *dsa); -// DSA_get0_q returns the size of |dsa|'s subgroup. +// DSA_get0_q returns the size of `dsa`'s subgroup. OPENSSL_EXPORT const BIGNUM *DSA_get0_q(const DSA *dsa); -// DSA_get0_g returns |dsa|'s group generator. +// DSA_get0_g returns `dsa`'s group generator. OPENSSL_EXPORT const BIGNUM *DSA_get0_g(const DSA *dsa); -// DSA_get0_key sets |*out_pub_key| and |*out_priv_key|, if non-NULL, to |dsa|'s -// public and private key, respectively. If |dsa| is a public key, the private +// DSA_get0_key sets `*out_pub_key` and `*out_priv_key`, if non-NULL, to `dsa`'s +// public and private key, respectively. If `dsa` is a public key, the private // key will be set to NULL. OPENSSL_EXPORT void DSA_get0_key(const DSA *dsa, const BIGNUM **out_pub_key, const BIGNUM **out_priv_key); -// DSA_get0_pqg sets |*out_p|, |*out_q|, and |*out_g|, if non-NULL, to |dsa|'s +// DSA_get0_pqg sets `*out_p`, `*out_q`, and `*out_g`, if non-NULL, to `dsa`'s // p, q, and g parameters, respectively. OPENSSL_EXPORT void DSA_get0_pqg(const DSA *dsa, const BIGNUM **out_p, const BIGNUM **out_q, const BIGNUM **out_g); -// DSA_set0_key sets |dsa|'s public and private key to |pub_key| and |priv_key|, +// DSA_set0_key sets `dsa`'s public and private key to `pub_key` and `priv_key`, // respectively, if non-NULL. On success, it takes ownership of each argument // and returns one. Otherwise, it returns zero. // -// |priv_key| may be NULL, but |pub_key| must either be non-NULL or already -// configured on |dsa|. +// `priv_key` may be NULL, but `pub_key` must either be non-NULL or already +// configured on `dsa`. OPENSSL_EXPORT int DSA_set0_key(DSA *dsa, BIGNUM *pub_key, BIGNUM *priv_key); -// DSA_set0_pqg sets |dsa|'s parameters to |p|, |q|, and |g|, if non-NULL, and +// DSA_set0_pqg sets `dsa`'s parameters to `p`, `q`, and `g`, if non-NULL, and // takes ownership of them. On success, it takes ownership of each argument and // returns one. Otherwise, it returns zero. // -// Each argument must either be non-NULL or already configured on |dsa|. +// Each argument must either be non-NULL or already configured on `dsa`. OPENSSL_EXPORT int DSA_set0_pqg(DSA *dsa, BIGNUM *p, BIGNUM *q, BIGNUM *g); @@ -110,17 +110,17 @@ // the procedure given in FIPS 186-4, appendix A. // (http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf) // -// The larger prime will have a length of |bits| (e.g. 2048). The |seed| value +// The larger prime will have a length of `bits` (e.g. 2048). The `seed` value // allows others to generate and verify the same parameters and should be -// random input which is kept for reference. If |out_counter| or |out_h| are +// random input which is kept for reference. If `out_counter` or `out_h` are // not NULL then the counter and h value used in the generation are written to // them. // -// The |cb| argument is passed to |BN_generate_prime_ex| and is thus called +// The `cb` argument is passed to `BN_generate_prime_ex` and is thus called // during the generation process in order to indicate progress. See the // comments for that function for details. In addition to the calls made by -// |BN_generate_prime_ex|, |DSA_generate_parameters_ex| will call it with -// |event| equal to 2 and 3 at different stages of the process. +// `BN_generate_prime_ex`, `DSA_generate_parameters_ex` will call it with +// `event` equal to 2 and 3 at different stages of the process. // // It returns one on success and zero otherwise. OPENSSL_EXPORT int DSA_generate_parameters_ex(DSA *dsa, unsigned bits, @@ -129,14 +129,14 @@ unsigned long *out_h, BN_GENCB *cb); -// DSAparams_dup returns a freshly allocated |DSA| that contains a copy of the -// parameters from |dsa|. It returns NULL on error. +// DSAparams_dup returns a freshly allocated `DSA` that contains a copy of the +// parameters from `dsa`. It returns NULL on error. OPENSSL_EXPORT DSA *DSAparams_dup(const DSA *dsa); // Key generation. -// DSA_generate_key generates a public/private key pair in |dsa|, which must +// DSA_generate_key generates a public/private key pair in `dsa`, which must // already have parameters setup. It returns one on success and zero on // error. OPENSSL_EXPORT int DSA_generate_key(DSA *dsa); @@ -144,49 +144,49 @@ // Signatures. -// DSA_SIG_st (aka |DSA_SIG|) contains a DSA signature as a pair of integers. +// DSA_SIG_st (aka `DSA_SIG`) contains a DSA signature as a pair of integers. struct DSA_SIG_st { BIGNUM *r, *s; }; // DSA_SIG_new returns a freshly allocated, DIG_SIG structure or NULL on error. -// Both |r| and |s| in the signature will be NULL. +// Both `r` and `s` in the signature will be NULL. OPENSSL_EXPORT DSA_SIG *DSA_SIG_new(void); -// DSA_SIG_free frees the contents of |sig| and then frees |sig| itself. +// DSA_SIG_free frees the contents of `sig` and then frees `sig` itself. OPENSSL_EXPORT void DSA_SIG_free(DSA_SIG *sig); -// DSA_SIG_get0 sets |*out_r| and |*out_s|, if non-NULL, to the two components -// of |sig|. +// DSA_SIG_get0 sets `*out_r` and `*out_s`, if non-NULL, to the two components +// of `sig`. OPENSSL_EXPORT void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **out_r, const BIGNUM **out_s); -// DSA_SIG_set0 sets |sig|'s components to |r| and |s|, neither of which may be +// DSA_SIG_set0 sets `sig`'s components to `r` and `s`, neither of which may be // NULL. On success, it takes ownership of each argument and returns one. // Otherwise, it returns zero. OPENSSL_EXPORT int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s); -// DSA_do_sign returns a signature of the hash in |digest| by the key in |dsa| +// DSA_do_sign returns a signature of the hash in `digest` by the key in `dsa` // and returns an allocated, DSA_SIG structure, or NULL on error. OPENSSL_EXPORT DSA_SIG *DSA_do_sign(const uint8_t *digest, size_t digest_len, const DSA *dsa); -// DSA_do_verify verifies that |sig| is a valid signature, by the public key in -// |dsa|, of the hash in |digest|. It returns one if so, zero if invalid and -1 +// DSA_do_verify verifies that `sig` is a valid signature, by the public key in +// `dsa`, of the hash in `digest`. It returns one if so, zero if invalid and -1 // on error. // // WARNING: do not use. This function returns -1 for error, 0 for invalid and 1 // for valid. However, this is dangerously different to the usual OpenSSL -// convention and could be a disaster if a user did |if (DSA_do_verify(...))|. -// Because of this, |DSA_check_signature| is a safer version of this. +// convention and could be a disaster if a user did `if (DSA_do_verify(...))`. +// Because of this, `DSA_check_signature` is a safer version of this. // // TODO(fork): deprecate. OPENSSL_EXPORT int DSA_do_verify(const uint8_t *digest, size_t digest_len, const DSA_SIG *sig, const DSA *dsa); -// DSA_do_check_signature sets |*out_valid| to zero. Then it verifies that |sig| -// is a valid signature, by the public key in |dsa| of the hash in |digest| -// and, if so, it sets |*out_valid| to one. +// DSA_do_check_signature sets `*out_valid` to zero. Then it verifies that `sig` +// is a valid signature, by the public key in `dsa` of the hash in `digest` +// and, if so, it sets `*out_valid` to one. // // It returns one if it was able to verify the signature as valid or invalid, // and zero on error. @@ -198,38 +198,38 @@ // ASN.1 signatures. // // These functions also perform DSA signature operations, but deal with ASN.1 -// encoded signatures as opposed to raw |BIGNUM|s. If you don't know what +// encoded signatures as opposed to raw `BIGNUM`s. If you don't know what // encoding a DSA signature is in, it's probably ASN.1. -// DSA_sign signs |digest| with the key in |dsa| and writes the resulting -// signature, in ASN.1 form, to |out_sig| and the length of the signature to -// |*out_siglen|. There must be, at least, |DSA_size(dsa)| bytes of space in -// |out_sig|. It returns one on success and zero otherwise. +// DSA_sign signs `digest` with the key in `dsa` and writes the resulting +// signature, in ASN.1 form, to `out_sig` and the length of the signature to +// `*out_siglen`. There must be, at least, `DSA_size(dsa)` bytes of space in +// `out_sig`. It returns one on success and zero otherwise. // -// (The |type| argument is ignored.) +// (The `type` argument is ignored.) OPENSSL_EXPORT int DSA_sign(int type, const uint8_t *digest, size_t digest_len, uint8_t *out_sig, unsigned int *out_siglen, const DSA *dsa); -// DSA_verify verifies that |sig| is a valid, ASN.1 signature, by the public -// key in |dsa|, of the hash in |digest|. It returns one if so, zero if invalid +// DSA_verify verifies that `sig` is a valid, ASN.1 signature, by the public +// key in `dsa`, of the hash in `digest`. It returns one if so, zero if invalid // and -1 on error. // -// (The |type| argument is ignored.) +// (The `type` argument is ignored.) // // WARNING: do not use. This function returns -1 for error, 0 for invalid and 1 // for valid. However, this is dangerously different to the usual OpenSSL -// convention and could be a disaster if a user did |if (DSA_do_verify(...))|. -// Because of this, |DSA_check_signature| is a safer version of this. +// convention and could be a disaster if a user did `if (DSA_do_verify(...))`. +// Because of this, `DSA_check_signature` is a safer version of this. // // TODO(fork): deprecate. OPENSSL_EXPORT int DSA_verify(int type, const uint8_t *digest, size_t digest_len, const uint8_t *sig, size_t sig_len, const DSA *dsa); -// DSA_check_signature sets |*out_valid| to zero. Then it verifies that |sig| -// is a valid, ASN.1 signature, by the public key in |dsa|, of the hash in -// |digest|. If so, it sets |*out_valid| to one. +// DSA_check_signature sets `*out_valid` to zero. Then it verifies that `sig` +// is a valid, ASN.1 signature, by the public key in `dsa`, of the hash in +// `digest`. If so, it sets `*out_valid` to one. // // It returns one if it was able to verify the signature as valid or invalid, // and zero on error. @@ -238,60 +238,60 @@ size_t sig_len, const DSA *dsa); // DSA_size returns the size, in bytes, of an ASN.1 encoded, DSA signature -// generated by |dsa|. Parameters must already have been setup in |dsa|. +// generated by `dsa`. Parameters must already have been setup in `dsa`. OPENSSL_EXPORT int DSA_size(const DSA *dsa); // ASN.1 encoding. -// DSA_SIG_parse parses a DER-encoded DSA-Sig-Value structure from |cbs| and -// advances |cbs|. It returns a newly-allocated |DSA_SIG| or NULL on error. +// DSA_SIG_parse parses a DER-encoded DSA-Sig-Value structure from `cbs` and +// advances `cbs`. It returns a newly-allocated `DSA_SIG` or NULL on error. OPENSSL_EXPORT DSA_SIG *DSA_SIG_parse(CBS *cbs); -// DSA_SIG_marshal marshals |sig| as a DER-encoded DSA-Sig-Value and appends the -// result to |cbb|. It returns one on success and zero on error. +// DSA_SIG_marshal marshals `sig` as a DER-encoded DSA-Sig-Value and appends the +// result to `cbb`. It returns one on success and zero on error. OPENSSL_EXPORT int DSA_SIG_marshal(CBB *cbb, const DSA_SIG *sig); -// DSA_parse_public_key parses a DER-encoded DSA public key from |cbs| and -// advances |cbs|. It returns a newly-allocated |DSA| or NULL on error. +// DSA_parse_public_key parses a DER-encoded DSA public key from `cbs` and +// advances `cbs`. It returns a newly-allocated `DSA` or NULL on error. OPENSSL_EXPORT DSA *DSA_parse_public_key(CBS *cbs); -// DSA_marshal_public_key marshals |dsa| as a DER-encoded DSA public key and -// appends the result to |cbb|. It returns one on success and zero on +// DSA_marshal_public_key marshals `dsa` as a DER-encoded DSA public key and +// appends the result to `cbb`. It returns one on success and zero on // failure. OPENSSL_EXPORT int DSA_marshal_public_key(CBB *cbb, const DSA *dsa); -// DSA_parse_private_key parses a DER-encoded DSA private key from |cbs| and -// advances |cbs|. It returns a newly-allocated |DSA| or NULL on error. +// DSA_parse_private_key parses a DER-encoded DSA private key from `cbs` and +// advances `cbs`. It returns a newly-allocated `DSA` or NULL on error. OPENSSL_EXPORT DSA *DSA_parse_private_key(CBS *cbs); -// DSA_marshal_private_key marshals |dsa| as a DER-encoded DSA private key and -// appends the result to |cbb|. It returns one on success and zero on +// DSA_marshal_private_key marshals `dsa` as a DER-encoded DSA private key and +// appends the result to `cbb`. It returns one on success and zero on // failure. OPENSSL_EXPORT int DSA_marshal_private_key(CBB *cbb, const DSA *dsa); // DSA_parse_parameters parses a DER-encoded Dss-Parms structure (RFC 3279) -// from |cbs| and advances |cbs|. It returns a newly-allocated |DSA| or NULL on +// from `cbs` and advances `cbs`. It returns a newly-allocated `DSA` or NULL on // error. OPENSSL_EXPORT DSA *DSA_parse_parameters(CBS *cbs); -// DSA_marshal_parameters marshals |dsa| as a DER-encoded Dss-Parms structure -// (RFC 3279) and appends the result to |cbb|. It returns one on success and +// DSA_marshal_parameters marshals `dsa` as a DER-encoded Dss-Parms structure +// (RFC 3279) and appends the result to `cbb`. It returns one on success and // zero on failure. OPENSSL_EXPORT int DSA_marshal_parameters(CBB *cbb, const DSA *dsa); // Conversion. -// DSA_dup_DH returns a |DH| constructed from the parameters of |dsa|. This is +// DSA_dup_DH returns a `DH` constructed from the parameters of `dsa`. This is // sometimes needed when Diffie-Hellman parameters are stored in the form of -// DSA parameters. It returns an allocated |DH| on success or NULL on error. +// DSA parameters. It returns an allocated `DH` on success or NULL on error. OPENSSL_EXPORT DH *DSA_dup_DH(const DSA *dsa); // ex_data functions. // -// See |ex_data.h| for details. +// See `ex_data.h` for details. OPENSSL_EXPORT int DSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_unused *unused, @@ -303,57 +303,57 @@ // Deprecated functions. -// d2i_DSA_SIG parses a DER-encoded DSA-Sig-Value structure from |len| bytes at -// |*inp|, as described in |d2i_SAMPLE|. +// d2i_DSA_SIG parses a DER-encoded DSA-Sig-Value structure from `len` bytes at +// `*inp`, as described in `d2i_SAMPLE`. // -// Use |DSA_SIG_parse| instead. +// Use `DSA_SIG_parse` instead. OPENSSL_EXPORT DSA_SIG *d2i_DSA_SIG(DSA_SIG **out_sig, const uint8_t **inp, long len); -// i2d_DSA_SIG marshals |in| to a DER-encoded DSA-Sig-Value structure, as -// described in |i2d_SAMPLE|. +// i2d_DSA_SIG marshals `in` to a DER-encoded DSA-Sig-Value structure, as +// described in `i2d_SAMPLE`. // -// Use |DSA_SIG_marshal| instead. +// Use `DSA_SIG_marshal` instead. OPENSSL_EXPORT int i2d_DSA_SIG(const DSA_SIG *in, uint8_t **outp); -// d2i_DSAPublicKey parses a DER-encoded DSA public key from |len| bytes at -// |*inp|, as described in |d2i_SAMPLE|. +// d2i_DSAPublicKey parses a DER-encoded DSA public key from `len` bytes at +// `*inp`, as described in `d2i_SAMPLE`. // -// Use |DSA_parse_public_key| instead. +// Use `DSA_parse_public_key` instead. OPENSSL_EXPORT DSA *d2i_DSAPublicKey(DSA **out, const uint8_t **inp, long len); -// i2d_DSAPublicKey marshals |in| as a DER-encoded DSA public key, as described -// in |i2d_SAMPLE|. +// i2d_DSAPublicKey marshals `in` as a DER-encoded DSA public key, as described +// in `i2d_SAMPLE`. // -// Use |DSA_marshal_public_key| instead. +// Use `DSA_marshal_public_key` instead. OPENSSL_EXPORT int i2d_DSAPublicKey(const DSA *in, uint8_t **outp); -// d2i_DSAPrivateKey parses a DER-encoded DSA private key from |len| bytes at -// |*inp|, as described in |d2i_SAMPLE|. +// d2i_DSAPrivateKey parses a DER-encoded DSA private key from `len` bytes at +// `*inp`, as described in `d2i_SAMPLE`. // -// Use |DSA_parse_private_key| instead. +// Use `DSA_parse_private_key` instead. OPENSSL_EXPORT DSA *d2i_DSAPrivateKey(DSA **out, const uint8_t **inp, long len); -// i2d_DSAPrivateKey marshals |in| as a DER-encoded DSA private key, as -// described in |i2d_SAMPLE|. +// i2d_DSAPrivateKey marshals `in` as a DER-encoded DSA private key, as +// described in `i2d_SAMPLE`. // -// Use |DSA_marshal_private_key| instead. +// Use `DSA_marshal_private_key` instead. OPENSSL_EXPORT int i2d_DSAPrivateKey(const DSA *in, uint8_t **outp); -// d2i_DSAparams parses a DER-encoded Dss-Parms structure (RFC 3279) from |len| -// bytes at |*inp|, as described in |d2i_SAMPLE|. +// d2i_DSAparams parses a DER-encoded Dss-Parms structure (RFC 3279) from `len` +// bytes at `*inp`, as described in `d2i_SAMPLE`. // -// Use |DSA_parse_parameters| instead. +// Use `DSA_parse_parameters` instead. OPENSSL_EXPORT DSA *d2i_DSAparams(DSA **out, const uint8_t **inp, long len); -// i2d_DSAparams marshals |in|'s parameters as a DER-encoded Dss-Parms structure -// (RFC 3279), as described in |i2d_SAMPLE|. +// i2d_DSAparams marshals `in`'s parameters as a DER-encoded Dss-Parms structure +// (RFC 3279), as described in `i2d_SAMPLE`. // -// Use |DSA_marshal_parameters| instead. +// Use `DSA_marshal_parameters` instead. OPENSSL_EXPORT int i2d_DSAparams(const DSA *in, uint8_t **outp); // DSA_generate_parameters is a deprecated version of -// |DSA_generate_parameters_ex| that creates and returns a |DSA*|. Don't use +// `DSA_generate_parameters_ex` that creates and returns a `DSA*`. Don't use // it. OPENSSL_EXPORT DSA *DSA_generate_parameters(int bits, unsigned char *seed, int seed_len, int *counter_ret,
diff --git a/include/openssl/ec.h b/include/openssl/ec.h index 2479228..e9ed971 100644 --- a/include/openssl/ec.h +++ b/include/openssl/ec.h
@@ -49,143 +49,143 @@ // Elliptic curve groups. // -// Elliptic curve groups are represented by |EC_GROUP| objects. Unlike OpenSSL, -// if limited to the APIs in this section, callers may treat |EC_GROUP|s as +// Elliptic curve groups are represented by `EC_GROUP` objects. Unlike OpenSSL, +// if limited to the APIs in this section, callers may treat `EC_GROUP`s as // static, immutable objects which do not need to be copied or released. In -// BoringSSL, only custom |EC_GROUP|s created by |EC_GROUP_new_curve_GFp| +// BoringSSL, only custom `EC_GROUP`s created by `EC_GROUP_new_curve_GFp` // (deprecated) are dynamic. // -// Callers may cast away |const| and use |EC_GROUP_dup| and |EC_GROUP_free| with +// Callers may cast away `const` and use `EC_GROUP_dup` and `EC_GROUP_free` with // static groups, for compatibility with OpenSSL or dynamic groups, but it is // otherwise unnecessary. -// EC_group_p224 returns an |EC_GROUP| for P-224, also known as secp224r1. +// EC_group_p224 returns an `EC_GROUP` for P-224, also known as secp224r1. OPENSSL_EXPORT const EC_GROUP *EC_group_p224(void); -// EC_group_p256 returns an |EC_GROUP| for P-256, also known as secp256r1 or +// EC_group_p256 returns an `EC_GROUP` for P-256, also known as secp256r1 or // prime256v1. OPENSSL_EXPORT const EC_GROUP *EC_group_p256(void); -// EC_group_p384 returns an |EC_GROUP| for P-384, also known as secp384r1. +// EC_group_p384 returns an `EC_GROUP` for P-384, also known as secp384r1. OPENSSL_EXPORT const EC_GROUP *EC_group_p384(void); -// EC_group_p521 returns an |EC_GROUP| for P-521, also known as secp521r1. +// EC_group_p521 returns an `EC_GROUP` for P-521, also known as secp521r1. OPENSSL_EXPORT const EC_GROUP *EC_group_p521(void); -// EC_GROUP_new_by_curve_name returns the |EC_GROUP| object for the elliptic -// curve specified by |nid|, or NULL on unsupported NID. For OpenSSL +// EC_GROUP_new_by_curve_name returns the `EC_GROUP` object for the elliptic +// curve specified by `nid`, or NULL on unsupported NID. For OpenSSL // compatibility, this function returns a non-const pointer which may be passed -// to |EC_GROUP_free|. However, the resulting object is actually static and -// calling |EC_GROUP_free| is optional. +// to `EC_GROUP_free`. However, the resulting object is actually static and +// calling `EC_GROUP_free` is optional. // // The supported NIDs are: -// - |NID_secp224r1| (P-224) -// - |NID_X9_62_prime256v1| (P-256) -// - |NID_secp384r1| (P-384) -// - |NID_secp521r1| (P-521) +// - `NID_secp224r1` (P-224) +// - `NID_X9_62_prime256v1` (P-256) +// - `NID_secp384r1` (P-384) +// - `NID_secp521r1` (P-521) // // Calling this function causes all four curves to be linked into the binary. -// Prefer calling |EC_group_*| to allow the static linker to drop unused curves. +// Prefer calling `EC_group_*` to allow the static linker to drop unused curves. // -// If in doubt, use |NID_X9_62_prime256v1|, or see the curve25519.h header for +// If in doubt, use `NID_X9_62_prime256v1`, or see the curve25519.h header for // more modern primitives. OPENSSL_EXPORT EC_GROUP *EC_GROUP_new_by_curve_name(int nid); -// EC_GROUP_cmp returns zero if |a| and |b| are the same group and non-zero +// EC_GROUP_cmp returns zero if `a` and `b` are the same group and non-zero // otherwise. OPENSSL_EXPORT int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ignored); -// EC_GROUP_get0_generator returns a pointer to the internal |EC_POINT| object -// in |group| that specifies the generator for the group. +// EC_GROUP_get0_generator returns a pointer to the internal `EC_POINT` object +// in `group` that specifies the generator for the group. OPENSSL_EXPORT const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); -// EC_GROUP_get0_order returns a pointer to the internal |BIGNUM| object in -// |group| that specifies the order of the group. +// EC_GROUP_get0_order returns a pointer to the internal `BIGNUM` object in +// `group` that specifies the order of the group. OPENSSL_EXPORT const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group); -// EC_GROUP_order_bits returns the number of bits of the order of |group|. +// EC_GROUP_order_bits returns the number of bits of the order of `group`. OPENSSL_EXPORT int EC_GROUP_order_bits(const EC_GROUP *group); -// EC_GROUP_get_cofactor sets |*cofactor| to the cofactor of |group|. It returns -// one on success and zero otherwise. |ctx| is ignored and may be NULL. +// EC_GROUP_get_cofactor sets `*cofactor` to the cofactor of `group`. It returns +// one on success and zero otherwise. `ctx` is ignored and may be NULL. OPENSSL_EXPORT int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); // EC_GROUP_get_curve_GFp gets various parameters about a group. It sets -// |*out_p| to the order of the coordinate field and |*out_a| and |*out_b| to +// `*out_p` to the order of the coordinate field and `*out_a` and `*out_b` to // the parameters of the curve when expressed as y² = x³ + ax + b. Any of the // output parameters can be NULL. It returns one on success and zero on -// error. |ctx| is ignored and may be NULL. +// error. `ctx` is ignored and may be NULL. OPENSSL_EXPORT int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *out_p, BIGNUM *out_a, BIGNUM *out_b, BN_CTX *ctx); -// EC_GROUP_get_curve_name returns a NID that identifies |group|. +// EC_GROUP_get_curve_name returns a NID that identifies `group`. OPENSSL_EXPORT int EC_GROUP_get_curve_name(const EC_GROUP *group); // EC_GROUP_get_degree returns the number of bits needed to represent an -// element of the field underlying |group|. +// element of the field underlying `group`. OPENSSL_EXPORT unsigned EC_GROUP_get_degree(const EC_GROUP *group); // EC_curve_nid2nist returns the NIST name of the elliptic curve specified by -// |nid|, or NULL if |nid| is not a NIST curve. For example, it returns "P-256" -// for |NID_X9_62_prime256v1|. +// `nid`, or NULL if `nid` is not a NIST curve. For example, it returns "P-256" +// for `NID_X9_62_prime256v1`. OPENSSL_EXPORT const char *EC_curve_nid2nist(int nid); // EC_curve_nist2nid returns the NID of the elliptic curve specified by the NIST -// name |name|, or |NID_undef| if |name| is not a recognized name. For example, -// it returns |NID_X9_62_prime256v1| for "P-256". +// name `name`, or `NID_undef` if `name` is not a recognized name. For example, +// it returns `NID_X9_62_prime256v1` for "P-256". OPENSSL_EXPORT int EC_curve_nist2nid(const char *name); // Points on elliptic curves. -// EC_POINT_new returns a fresh |EC_POINT| object in the given group, or NULL +// EC_POINT_new returns a fresh `EC_POINT` object in the given group, or NULL // on error. OPENSSL_EXPORT EC_POINT *EC_POINT_new(const EC_GROUP *group); -// EC_POINT_free frees |point| and the data that it points to. +// EC_POINT_free frees `point` and the data that it points to. OPENSSL_EXPORT void EC_POINT_free(EC_POINT *point); -// EC_POINT_copy sets |*dest| equal to |*src|. It returns one on success and +// EC_POINT_copy sets `*dest` equal to `*src`. It returns one on success and // zero otherwise. OPENSSL_EXPORT int EC_POINT_copy(EC_POINT *dest, const EC_POINT *src); -// EC_POINT_dup returns a fresh |EC_POINT| that contains the same values as -// |src|, or NULL on error. +// EC_POINT_dup returns a fresh `EC_POINT` that contains the same values as +// `src`, or NULL on error. OPENSSL_EXPORT EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); -// EC_POINT_set_to_infinity sets |point| to be the "point at infinity" for the +// EC_POINT_set_to_infinity sets `point` to be the "point at infinity" for the // given group. OPENSSL_EXPORT int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); -// EC_POINT_is_at_infinity returns one iff |point| is the point at infinity and +// EC_POINT_is_at_infinity returns one iff `point` is the point at infinity and // zero otherwise. OPENSSL_EXPORT int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *point); -// EC_POINT_is_on_curve returns one if |point| is an element of |group| and +// EC_POINT_is_on_curve returns one if `point` is an element of `group` and // and zero otherwise or when an error occurs. This is different from OpenSSL, -// which returns -1 on error. |ctx| is ignored and may be NULL. +// which returns -1 on error. `ctx` is ignored and may be NULL. OPENSSL_EXPORT int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); -// EC_POINT_cmp returns zero if |a| is equal to |b|, greater than zero if -// not equal and -1 on error. |ctx| is ignored and may be NULL. +// EC_POINT_cmp returns zero if `a` is equal to `b`, greater than zero if +// not equal and -1 on error. `ctx` is ignored and may be NULL. OPENSSL_EXPORT int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); // Point conversion. -// EC_POINT_get_affine_coordinates_GFp sets |x| and |y| to the affine value of -// |point|. It returns one on success and zero otherwise. |ctx| is ignored and +// EC_POINT_get_affine_coordinates_GFp sets `x` and `y` to the affine value of +// `point`. It returns one on success and zero otherwise. `ctx` is ignored and // may be NULL. // -// Either |x| or |y| may be NULL to skip computing that coordinate. This is +// Either `x` or `y` may be NULL to skip computing that coordinate. This is // slightly faster in the common case where only the x-coordinate is needed. OPENSSL_EXPORT int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, const EC_POINT *point, @@ -193,21 +193,21 @@ BN_CTX *ctx); // EC_POINT_get_affine_coordinates is an alias of -// |EC_POINT_get_affine_coordinates_GFp|. +// `EC_POINT_get_affine_coordinates_GFp`. OPENSSL_EXPORT int EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *point, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); -// EC_POINT_set_affine_coordinates_GFp sets the value of |point| to be -// (|x|, |y|). |ctx| is ignored and may be NULL. It returns one on success or +// EC_POINT_set_affine_coordinates_GFp sets the value of `point` to be +// (`x`, `y`). `ctx` is ignored and may be NULL. It returns one on success or // zero on error. It's considered an error if the point is not on the curve. // // Note that the corresponding function in OpenSSL versions prior to 1.0.2s does // not check if the point is on the curve. This is a security-critical check, so // code additionally supporting OpenSSL should repeat the check with -// |EC_POINT_is_on_curve| or check for older OpenSSL versions with -// |OPENSSL_VERSION_NUMBER|. +// `EC_POINT_is_on_curve` or check for older OpenSSL versions with +// `OPENSSL_VERSION_NUMBER`. OPENSSL_EXPORT int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *point, const BIGNUM *x, @@ -215,51 +215,51 @@ BN_CTX *ctx); // EC_POINT_set_affine_coordinates is an alias of -// |EC_POINT_set_affine_coordinates_GFp|. +// `EC_POINT_set_affine_coordinates_GFp`. OPENSSL_EXPORT int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *point, const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); -// EC_POINT_point2oct serialises |point| into the X9.62 form given by |form| -// into, at most, |max_out| bytes at |buf|. It returns the number of bytes -// written or zero on error if |buf| is non-NULL, else the number of bytes -// needed. |ctx| is ignored and may be NULL. +// EC_POINT_point2oct serialises `point` into the X9.62 form given by `form` +// into, at most, `max_out` bytes at `buf`. It returns the number of bytes +// written or zero on error if `buf` is non-NULL, else the number of bytes +// needed. `ctx` is ignored and may be NULL. OPENSSL_EXPORT size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *point, point_conversion_form_t form, uint8_t *buf, size_t max_out, BN_CTX *ctx); -// EC_POINT_point2buf serialises |point| into the X9.62 form given by |form| to -// a newly-allocated buffer and sets |*out_buf| to point to it. It returns the +// EC_POINT_point2buf serialises `point` into the X9.62 form given by `form` to +// a newly-allocated buffer and sets `*out_buf` to point to it. It returns the // length of the result on success or zero on error. The caller must release -// |*out_buf| with |OPENSSL_free| when done. |ctx| is ignored and may be NULL. +// `*out_buf` with `OPENSSL_free` when done. `ctx` is ignored and may be NULL. OPENSSL_EXPORT size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point, point_conversion_form_t form, uint8_t **out_buf, BN_CTX *ctx); -// EC_POINT_point2cbb behaves like |EC_POINT_point2oct| but appends the -// serialised point to |cbb|. It returns one on success and zero on error. |ctx| +// EC_POINT_point2cbb behaves like `EC_POINT_point2oct` but appends the +// serialised point to `cbb`. It returns one on success and zero on error. `ctx` // is ignored and may be NULL. OPENSSL_EXPORT int EC_POINT_point2cbb(CBB *out, const EC_GROUP *group, const EC_POINT *point, point_conversion_form_t form, BN_CTX *ctx); -// EC_POINT_oct2point sets |point| from |len| bytes of X9.62 format -// serialisation in |buf|. It returns one on success and zero on error. |ctx| -// may be NULL. It's considered an error if |buf| does not represent a point on +// EC_POINT_oct2point sets `point` from `len` bytes of X9.62 format +// serialisation in `buf`. It returns one on success and zero on error. `ctx` +// may be NULL. It's considered an error if `buf` does not represent a point on // the curve. OPENSSL_EXPORT int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *point, const uint8_t *buf, size_t len, BN_CTX *ctx); -// EC_POINT_set_compressed_coordinates_GFp sets |point| to equal the point with -// the given |x| coordinate and the y coordinate specified by |y_bit| (see -// X9.62). It returns one on success and zero otherwise. |ctx| may be NULL. +// EC_POINT_set_compressed_coordinates_GFp sets `point` to equal the point with +// the given `x` coordinate and the y coordinate specified by `y_bit` (see +// X9.62). It returns one on success and zero otherwise. `ctx` may be NULL. OPENSSL_EXPORT int EC_POINT_set_compressed_coordinates_GFp( const EC_GROUP *group, EC_POINT *point, const BIGNUM *x, int y_bit, BN_CTX *ctx); @@ -267,24 +267,24 @@ // Group operations. -// EC_POINT_add sets |r| equal to |a| plus |b|. It returns one on success and -// zero otherwise. |ctx| is ignored and may be NULL. +// EC_POINT_add sets `r` equal to `a` plus `b`. It returns one on success and +// zero otherwise. `ctx` is ignored and may be NULL. OPENSSL_EXPORT int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); -// EC_POINT_dbl sets |r| equal to |a| plus |a|. It returns one on success and -// zero otherwise. |ctx| is ignored and may be NULL. +// EC_POINT_dbl sets `r` equal to `a` plus `a`. It returns one on success and +// zero otherwise. `ctx` is ignored and may be NULL. OPENSSL_EXPORT int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); -// EC_POINT_invert sets |a| equal to minus |a|. It returns one on success and -// zero otherwise. |ctx| is ignored and may be NULL. +// EC_POINT_invert sets `a` equal to minus `a`. It returns one on success and +// zero otherwise. `ctx` is ignored and may be NULL. OPENSSL_EXPORT int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); // EC_POINT_mul sets r = generator*n + q*m. It returns one on success and zero -// otherwise. |ctx| may be NULL. +// otherwise. `ctx` may be NULL. OPENSSL_EXPORT int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); @@ -292,44 +292,44 @@ // Hash-to-curve. // -// The following functions implement primitives from RFC 9380. The |dst| +// The following functions implement primitives from RFC 9380. The `dst` // parameter in each function is the domain separation tag and must be unique -// for each protocol and between the |hash_to_curve| and |hash_to_scalar| +// for each protocol and between the `hash_to_curve` and `hash_to_scalar` // variants. See section 3.1 of the spec for additional guidance on this // parameter. -// EC_hash_to_curve_p256_xmd_sha256_sswu hashes |msg| to a point on |group| and -// writes the result to |out|, implementing the P256_XMD:SHA-256_SSWU_RO_ suite +// EC_hash_to_curve_p256_xmd_sha256_sswu hashes `msg` to a point on `group` and +// writes the result to `out`, implementing the P256_XMD:SHA-256_SSWU_RO_ suite // from RFC 9380. It returns one on success and zero on error. OPENSSL_EXPORT int EC_hash_to_curve_p256_xmd_sha256_sswu( const EC_GROUP *group, EC_POINT *out, const uint8_t *dst, size_t dst_len, const uint8_t *msg, size_t msg_len); -// EC_hash_to_curve_p384_xmd_sha384_sswu hashes |msg| to a point on |group| and -// writes the result to |out|, implementing the P384_XMD:SHA-384_SSWU_RO_ suite +// EC_hash_to_curve_p384_xmd_sha384_sswu hashes `msg` to a point on `group` and +// writes the result to `out`, implementing the P384_XMD:SHA-384_SSWU_RO_ suite // from RFC 9380. It returns one on success and zero on error. OPENSSL_EXPORT int EC_hash_to_curve_p384_xmd_sha384_sswu( const EC_GROUP *group, EC_POINT *out, const uint8_t *dst, size_t dst_len, const uint8_t *msg, size_t msg_len); -// EC_encode_to_curve_p256_xmd_sha256_sswu hashes |msg| to a point on |group| -// and writes the result to |out|, implementing the P256_XMD:SHA-256_SSWU_NU_ +// EC_encode_to_curve_p256_xmd_sha256_sswu hashes `msg` to a point on `group` +// and writes the result to `out`, implementing the P256_XMD:SHA-256_SSWU_NU_ // suite from RFC 9380. It returns one on success and zero on error. // -// This is a nonuniform encoding from byte strings to points in |group|. That -// is, the set of possible outputs is only a fraction of the points in |group|, +// This is a nonuniform encoding from byte strings to points in `group`. That +// is, the set of possible outputs is only a fraction of the points in `group`, // and some points in this set are more likely to be output than others. See // also RFC 9380, section 10.4 OPENSSL_EXPORT int EC_encode_to_curve_p256_xmd_sha256_sswu( const EC_GROUP *group, EC_POINT *out, const uint8_t *dst, size_t dst_len, const uint8_t *msg, size_t msg_len); -// EC_encode_to_curve_p384_xmd_sha384_sswu hashes |msg| to a point on |group| -// and writes the result to |out|, implementing the P384_XMD:SHA-384_SSWU_NU_ +// EC_encode_to_curve_p384_xmd_sha384_sswu hashes `msg` to a point on `group` +// and writes the result to `out`, implementing the P384_XMD:SHA-384_SSWU_NU_ // suite from RFC 9380. It returns one on success and zero on error. // -// This is a nonuniform encoding from byte strings to points in |group|. That -// is, the set of possible outputs is only a fraction of the points in |group|, +// This is a nonuniform encoding from byte strings to points in `group`. That +// is, the set of possible outputs is only a fraction of the points in `group`, // and some points in this set are more likely to be output than others. See // also RFC 9380, section 10.4 OPENSSL_EXPORT int EC_encode_to_curve_p384_xmd_sha384_sswu( @@ -339,61 +339,61 @@ // Deprecated functions. -// EC_GROUP_free releases a reference to |group|, if |group| was created by -// |EC_GROUP_new_curve_GFp|. If |group| is static, it does nothing. +// EC_GROUP_free releases a reference to `group`, if `group` was created by +// `EC_GROUP_new_curve_GFp`. If `group` is static, it does nothing. // // This function exists for OpenSSL compatibility, and to manage dynamic -// |EC_GROUP|s constructed by |EC_GROUP_new_curve_GFp|. Callers that do not need +// `EC_GROUP`s constructed by `EC_GROUP_new_curve_GFp`. Callers that do not need // either may ignore this function. OPENSSL_EXPORT void EC_GROUP_free(EC_GROUP *group); -// EC_GROUP_dup increments |group|'s reference count and returns it, if |group| -// was created by |EC_GROUP_new_curve_GFp|. If |group| is static, it simply -// returns |group|. +// EC_GROUP_dup increments `group`'s reference count and returns it, if `group` +// was created by `EC_GROUP_new_curve_GFp`. If `group` is static, it simply +// returns `group`. // // This function exists for OpenSSL compatibility, and to manage dynamic -// |EC_GROUP|s constructed by |EC_GROUP_new_curve_GFp|. Callers that do not need +// `EC_GROUP`s constructed by `EC_GROUP_new_curve_GFp`. Callers that do not need // either may ignore this function. OPENSSL_EXPORT EC_GROUP *EC_GROUP_dup(const EC_GROUP *group); // EC_GROUP_new_curve_GFp creates a new, arbitrary elliptic curve group based // on the equation y² = x³ + a·x + b. It returns the new group or NULL on // error. The lifetime of the resulting object must be managed with -// |EC_GROUP_dup| and |EC_GROUP_free|. +// `EC_GROUP_dup` and `EC_GROUP_free`. // // This new group has no generator. It is an error to use a generator-less group -// with any functions except for |EC_GROUP_free|, |EC_POINT_new|, -// |EC_POINT_set_affine_coordinates_GFp|, and |EC_GROUP_set_generator|. +// with any functions except for `EC_GROUP_free`, `EC_POINT_new`, +// `EC_POINT_set_affine_coordinates_GFp`, and `EC_GROUP_set_generator`. // -// |EC_GROUP|s returned by this function will always compare as unequal via -// |EC_GROUP_cmp| (even to themselves). |EC_GROUP_get_curve_name| will always -// return |NID_undef|. +// `EC_GROUP`s returned by this function will always compare as unequal via +// `EC_GROUP_cmp` (even to themselves). `EC_GROUP_get_curve_name` will always +// return `NID_undef`. // // This function is provided for compatibility with some legacy applications -// only. Avoid using arbitrary curves and use |EC_GROUP_new_by_curve_name| +// only. Avoid using arbitrary curves and use `EC_GROUP_new_by_curve_name` // instead. This ensures the result meets preconditions necessary for // elliptic curve algorithms to function correctly and securely. // // Given invalid parameters, this function may fail or it may return an -// |EC_GROUP| which breaks these preconditions. Subsequent operations may then +// `EC_GROUP` which breaks these preconditions. Subsequent operations may then // return arbitrary, incorrect values. Callers should not pass // attacker-controlled values to this function. OPENSSL_EXPORT EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); -// EC_GROUP_set_generator sets the generator for |group| to |generator|, which -// must have the given order and cofactor. It may only be used with |EC_GROUP| -// objects returned by |EC_GROUP_new_curve_GFp| and may only be used once on -// each group. |generator| must have been created using |group|. +// EC_GROUP_set_generator sets the generator for `group` to `generator`, which +// must have the given order and cofactor. It may only be used with `EC_GROUP` +// objects returned by `EC_GROUP_new_curve_GFp` and may only be used once on +// each group. `generator` must have been created using `group`. OPENSSL_EXPORT int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); -// EC_GROUP_get_order sets |*order| to the order of |group|, if it's not -// NULL. It returns one on success and zero otherwise. |ctx| is ignored and may -// be NULL. Use |EC_GROUP_get0_order| instead. +// EC_GROUP_get_order sets `*order` to the order of `group`, if it's not +// NULL. It returns one on success and zero otherwise. `ctx` is ignored and may +// be NULL. Use `EC_GROUP_get0_order` instead. OPENSSL_EXPORT int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); @@ -403,7 +403,7 @@ // EC_GROUP_set_asn1_flag does nothing. OPENSSL_EXPORT void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); -// EC_GROUP_get_asn1_flag returns |OPENSSL_EC_NAMED_CURVE|. +// EC_GROUP_get_asn1_flag returns `OPENSSL_EC_NAMED_CURVE`. OPENSSL_EXPORT int EC_GROUP_get_asn1_flag(const EC_GROUP *group); typedef struct ec_method_st EC_METHOD; @@ -414,8 +414,8 @@ // EC_METHOD_get_field_type returns NID_X9_62_prime_field. OPENSSL_EXPORT int EC_METHOD_get_field_type(const EC_METHOD *meth); -// EC_GROUP_set_point_conversion_form aborts the process if |form| is not -// |POINT_CONVERSION_UNCOMPRESSED| and otherwise does nothing. +// EC_GROUP_set_point_conversion_form aborts the process if `form` is not +// `POINT_CONVERSION_UNCOMPRESSED` and otherwise does nothing. OPENSSL_EXPORT void EC_GROUP_set_point_conversion_form( EC_GROUP *group, point_conversion_form_t form); @@ -425,15 +425,15 @@ const char *comment; } EC_builtin_curve; -// EC_get_builtin_curves writes at most |max_num_curves| elements to -// |out_curves| and returns the total number that it would have written, had -// |max_num_curves| been large enough. +// EC_get_builtin_curves writes at most `max_num_curves` elements to +// `out_curves` and returns the total number that it would have written, had +// `max_num_curves` been large enough. // -// The |EC_builtin_curve| items describe the supported elliptic curves. +// The `EC_builtin_curve` items describe the supported elliptic curves. OPENSSL_EXPORT size_t EC_get_builtin_curves(EC_builtin_curve *out_curves, size_t max_num_curves); -// EC_POINT_clear_free calls |EC_POINT_free|. +// EC_POINT_clear_free calls `EC_POINT_free`. OPENSSL_EXPORT void EC_POINT_clear_free(EC_POINT *point);
diff --git a/include/openssl/ec_key.h b/include/openssl/ec_key.h index 47d5063..2ab696c 100644 --- a/include/openssl/ec_key.h +++ b/include/openssl/ec_key.h
@@ -33,83 +33,83 @@ // EC key objects. // -// An |EC_KEY| object represents a public or private EC key. A given object may +// An `EC_KEY` object represents a public or private EC key. A given object may // be used concurrently on multiple threads by non-mutating functions, provided // no other thread is concurrently calling a mutating function. Unless otherwise -// documented, functions which take a |const| pointer are non-mutating and -// functions which take a non-|const| pointer are mutating. +// documented, functions which take a `const` pointer are non-mutating and +// functions which take a non-`const` pointer are mutating. -// EC_KEY_new returns a fresh |EC_KEY| object or NULL on error. +// EC_KEY_new returns a fresh `EC_KEY` object or NULL on error. OPENSSL_EXPORT EC_KEY *EC_KEY_new(void); -// EC_KEY_new_method acts the same as |EC_KEY_new|, but takes an explicit -// |ENGINE|. +// EC_KEY_new_method acts the same as `EC_KEY_new`, but takes an explicit +// `ENGINE`. OPENSSL_EXPORT EC_KEY *EC_KEY_new_method(const ENGINE *engine); -// EC_KEY_new_by_curve_name returns a fresh EC_KEY for group specified by |nid| +// EC_KEY_new_by_curve_name returns a fresh EC_KEY for group specified by `nid` // or NULL on error. OPENSSL_EXPORT EC_KEY *EC_KEY_new_by_curve_name(int nid); -// EC_KEY_free frees all the data owned by |key| and |key| itself. +// EC_KEY_free frees all the data owned by `key` and `key` itself. OPENSSL_EXPORT void EC_KEY_free(EC_KEY *key); -// EC_KEY_dup returns a fresh copy of |src| or NULL on error. +// EC_KEY_dup returns a fresh copy of `src` or NULL on error. OPENSSL_EXPORT EC_KEY *EC_KEY_dup(const EC_KEY *src); -// EC_KEY_up_ref increases the reference count of |key| and returns one. It does -// not mutate |key| for thread-safety purposes and may be used concurrently. +// EC_KEY_up_ref increases the reference count of `key` and returns one. It does +// not mutate `key` for thread-safety purposes and may be used concurrently. OPENSSL_EXPORT int EC_KEY_up_ref(EC_KEY *key); -// EC_KEY_is_opaque returns one if |key| is opaque and doesn't expose its key +// EC_KEY_is_opaque returns one if `key` is opaque and doesn't expose its key // material. Otherwise it return zero. OPENSSL_EXPORT int EC_KEY_is_opaque(const EC_KEY *key); -// EC_KEY_get0_group returns a pointer to the |EC_GROUP| object inside |key|. +// EC_KEY_get0_group returns a pointer to the `EC_GROUP` object inside `key`. OPENSSL_EXPORT const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); -// EC_KEY_set_group sets the |EC_GROUP| object that |key| will use to |group|. -// It returns one on success and zero if |key| is already configured with a +// EC_KEY_set_group sets the `EC_GROUP` object that `key` will use to `group`. +// It returns one on success and zero if `key` is already configured with a // different group. OPENSSL_EXPORT int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); -// EC_KEY_get0_private_key returns a pointer to the private key inside |key|. +// EC_KEY_get0_private_key returns a pointer to the private key inside `key`. OPENSSL_EXPORT const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); -// EC_KEY_set_private_key sets the private key of |key| to |priv|. It returns -// one on success and zero otherwise. |key| must already have had a group -// configured (see |EC_KEY_set_group| and |EC_KEY_new_by_curve_name|). +// EC_KEY_set_private_key sets the private key of `key` to `priv`. It returns +// one on success and zero otherwise. `key` must already have had a group +// configured (see `EC_KEY_set_group` and `EC_KEY_new_by_curve_name`). OPENSSL_EXPORT int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *priv); // EC_KEY_get0_public_key returns a pointer to the public key point inside -// |key|. +// `key`. OPENSSL_EXPORT const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); -// EC_KEY_set_public_key sets the public key of |key| to |pub|, by copying it. -// It returns one on success and zero otherwise. |key| must already have had a -// group configured (see |EC_KEY_set_group| and |EC_KEY_new_by_curve_name|), and -// |pub| must also belong to that group, and must not be the point at infinity. +// EC_KEY_set_public_key sets the public key of `key` to `pub`, by copying it. +// It returns one on success and zero otherwise. `key` must already have had a +// group configured (see `EC_KEY_set_group` and `EC_KEY_new_by_curve_name`), and +// `pub` must also belong to that group, and must not be the point at infinity. OPENSSL_EXPORT int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); #define EC_PKEY_NO_PARAMETERS 0x001 #define EC_PKEY_NO_PUBKEY 0x002 -// EC_KEY_get_enc_flags returns the encoding flags for |key|, which is a -// bitwise-OR of |EC_PKEY_*| values. +// EC_KEY_get_enc_flags returns the encoding flags for `key`, which is a +// bitwise-OR of `EC_PKEY_*` values. OPENSSL_EXPORT unsigned EC_KEY_get_enc_flags(const EC_KEY *key); -// EC_KEY_set_enc_flags sets the encoding flags for |key|, which is a -// bitwise-OR of |EC_PKEY_*| values. +// EC_KEY_set_enc_flags sets the encoding flags for `key`, which is a +// bitwise-OR of `EC_PKEY_*` values. OPENSSL_EXPORT void EC_KEY_set_enc_flags(EC_KEY *key, unsigned flags); // EC_KEY_get_conv_form returns the conversation form that will be used by -// |key|. +// `key`. OPENSSL_EXPORT point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); -// EC_KEY_set_conv_form sets the conversion form to be used by |key|. +// EC_KEY_set_conv_form sets the conversion form to be used by `key`. OPENSSL_EXPORT void EC_KEY_set_conv_form(EC_KEY *key, point_conversion_form_t cform); -// EC_KEY_check_key performs several checks on |key| (possibly including an +// EC_KEY_check_key performs several checks on `key` (possibly including an // expensive check that the public key is in the primary subgroup). It returns // one if all checks pass and zero otherwise. If it returns zero then detail // about the problem can be found on the error stack. @@ -120,70 +120,70 @@ // 5.6.2.1.4. It returns one if it passes and zero otherwise. OPENSSL_EXPORT int EC_KEY_check_fips(const EC_KEY *key); -// EC_KEY_set_public_key_affine_coordinates sets the public key in |key| to -// (|x|, |y|). It returns one on success and zero on error. It's considered an -// error if |x| and |y| do not represent a point on |key|'s curve. +// EC_KEY_set_public_key_affine_coordinates sets the public key in `key` to +// (`x`, `y`). It returns one on success and zero on error. It's considered an +// error if `x` and `y` do not represent a point on `key`'s curve. OPENSSL_EXPORT int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, const BIGNUM *x, const BIGNUM *y); -// EC_KEY_oct2key decodes |len| bytes from |in| as an EC public key in X9.62 -// form. |key| must already have a group configured. On success, it sets the -// public key in |key| to the result and returns one. Otherwise, it returns -// zero. |ctx| may be NULL. +// EC_KEY_oct2key decodes `len` bytes from `in` as an EC public key in X9.62 +// form. `key` must already have a group configured. On success, it sets the +// public key in `key` to the result and returns one. Otherwise, it returns +// zero. `ctx` may be NULL. OPENSSL_EXPORT int EC_KEY_oct2key(EC_KEY *key, const uint8_t *in, size_t len, BN_CTX *ctx); -// EC_KEY_key2buf behaves like |EC_POINT_point2buf|, except it encodes the -// public key in |key|. |ctx| is ignored and may be NULL. +// EC_KEY_key2buf behaves like `EC_POINT_point2buf`, except it encodes the +// public key in `key`. `ctx` is ignored and may be NULL. OPENSSL_EXPORT size_t EC_KEY_key2buf(const EC_KEY *key, point_conversion_form_t form, uint8_t **out_buf, BN_CTX *ctx); -// EC_KEY_oct2priv decodes a big-endian, zero-padded integer from |len| bytes -// from |in| and sets |key|'s private key to the result. It returns one on -// success and zero on error. The input must be padded to the size of |key|'s +// EC_KEY_oct2priv decodes a big-endian, zero-padded integer from `len` bytes +// from `in` and sets `key`'s private key to the result. It returns one on +// success and zero on error. The input must be padded to the size of `key`'s // group order. OPENSSL_EXPORT int EC_KEY_oct2priv(EC_KEY *key, const uint8_t *in, size_t len); -// EC_KEY_priv2oct serializes |key|'s private key as a big-endian integer, -// zero-padded to the size of |key|'s group order and writes the result to at -// most |max_out| bytes of |out|. It returns the number of bytes written on -// success and zero on error. If |out| is NULL, it returns the number of bytes +// EC_KEY_priv2oct serializes `key`'s private key as a big-endian integer, +// zero-padded to the size of `key`'s group order and writes the result to at +// most `max_out` bytes of `out`. It returns the number of bytes written on +// success and zero on error. If `out` is NULL, it returns the number of bytes // needed without writing anything. OPENSSL_EXPORT size_t EC_KEY_priv2oct(const EC_KEY *key, uint8_t *out, size_t max_out); -// EC_KEY_priv2buf behaves like |EC_KEY_priv2oct| but sets |*out_buf| to a +// EC_KEY_priv2buf behaves like `EC_KEY_priv2oct` but sets `*out_buf` to a // newly-allocated buffer containing the result. It returns the size of the -// result on success and zero on error. The caller must release |*out_buf| with -// |OPENSSL_free| when done. +// result on success and zero on error. The caller must release `*out_buf` with +// `OPENSSL_free` when done. OPENSSL_EXPORT size_t EC_KEY_priv2buf(const EC_KEY *key, uint8_t **out_buf); // Key generation. // EC_KEY_generate_key generates a random, private key, calculates the -// corresponding public key and stores both in |key|. It returns one on success +// corresponding public key and stores both in `key`. It returns one on success // or zero otherwise. OPENSSL_EXPORT int EC_KEY_generate_key(EC_KEY *key); -// EC_KEY_generate_key_fips behaves like |EC_KEY_generate_key| but performs +// EC_KEY_generate_key_fips behaves like `EC_KEY_generate_key` but performs // additional checks for FIPS compliance. This function is applicable when // generating keys for either signing/verification or key agreement because // both types of consistency check (PCT) are performed. OPENSSL_EXPORT int EC_KEY_generate_key_fips(EC_KEY *key); -// EC_KEY_derive_from_secret deterministically derives a private key for |group| -// from an input secret using HKDF-SHA256. It returns a newly-allocated |EC_KEY| -// on success or NULL on error. |secret| must not be used in any other +// EC_KEY_derive_from_secret deterministically derives a private key for `group` +// from an input secret using HKDF-SHA256. It returns a newly-allocated `EC_KEY` +// on success or NULL on error. `secret` must not be used in any other // algorithm. If using a base secret for multiple operations, derive separate // values with a KDF such as HKDF first. // // Note this function implements an arbitrary derivation scheme, rather than any // particular standard one. New protocols are recommended to use X25519 and // Ed25519, which have standard byte import functions. See -// |X25519_public_from_private| and |ED25519_keypair_from_seed|. +// `X25519_public_from_private` and `ED25519_keypair_from_seed`. OPENSSL_EXPORT EC_KEY *EC_KEY_derive_from_secret(const EC_GROUP *group, const uint8_t *secret, size_t secret_len); @@ -192,45 +192,45 @@ // Serialisation. // EC_KEY_parse_private_key parses a DER-encoded ECPrivateKey structure (RFC -// 5915) from |cbs| and advances |cbs|. It returns a newly-allocated |EC_KEY| or -// NULL on error. If |group| is non-null, the parameters field of the -// ECPrivateKey may be omitted (but must match |group| if present). Otherwise, +// 5915) from `cbs` and advances `cbs`. It returns a newly-allocated `EC_KEY` or +// NULL on error. If `group` is non-null, the parameters field of the +// ECPrivateKey may be omitted (but must match `group` if present). Otherwise, // the parameters field is required. OPENSSL_EXPORT EC_KEY *EC_KEY_parse_private_key(CBS *cbs, const EC_GROUP *group); -// EC_KEY_marshal_private_key marshals |key| as a DER-encoded ECPrivateKey -// structure (RFC 5915) and appends the result to |cbb|. It returns one on -// success and zero on failure. |enc_flags| is a combination of |EC_PKEY_*| +// EC_KEY_marshal_private_key marshals `key` as a DER-encoded ECPrivateKey +// structure (RFC 5915) and appends the result to `cbb`. It returns one on +// success and zero on failure. `enc_flags` is a combination of `EC_PKEY_*` // values and controls whether corresponding fields are omitted. OPENSSL_EXPORT int EC_KEY_marshal_private_key(CBB *cbb, const EC_KEY *key, unsigned enc_flags); // EC_KEY_parse_curve_name parses a DER-encoded OBJECT IDENTIFIER as a curve -// name from |cbs| and advances |cbs|. It returns the decoded |EC_GROUP| or NULL +// name from `cbs` and advances `cbs`. It returns the decoded `EC_GROUP` or NULL // on error. // // This function returns a non-const pointer which may be passed to -// |EC_GROUP_free|. However, the resulting object is actually static and calling -// |EC_GROUP_free| is optional. +// `EC_GROUP_free`. However, the resulting object is actually static and calling +// `EC_GROUP_free` is optional. // // TODO(davidben): Make this return a const pointer, if it does not break too // many callers. OPENSSL_EXPORT EC_GROUP *EC_KEY_parse_curve_name(CBS *cbs); -// EC_KEY_marshal_curve_name marshals |group| as a DER-encoded OBJECT IDENTIFIER -// and appends the result to |cbb|. It returns one on success and zero on +// EC_KEY_marshal_curve_name marshals `group` as a DER-encoded OBJECT IDENTIFIER +// and appends the result to `cbb`. It returns one on success and zero on // failure. OPENSSL_EXPORT int EC_KEY_marshal_curve_name(CBB *cbb, const EC_GROUP *group); // EC_KEY_parse_parameters parses a DER-encoded ECParameters structure (RFC -// 5480) from |cbs| and advances |cbs|. It returns the resulting |EC_GROUP| or +// 5480) from `cbs` and advances `cbs`. It returns the resulting `EC_GROUP` or // NULL on error. It supports the namedCurve and specifiedCurve options, but use -// of specifiedCurve is deprecated. Use |EC_KEY_parse_curve_name| instead. +// of specifiedCurve is deprecated. Use `EC_KEY_parse_curve_name` instead. // // This function returns a non-const pointer which may be passed to -// |EC_GROUP_free|. However, the resulting object is actually static and calling -// |EC_GROUP_free| is optional. +// `EC_GROUP_free`. However, the resulting object is actually static and calling +// `EC_GROUP_free` is optional. // // TODO(davidben): Make this return a const pointer, if it does not break too // many callers. @@ -239,7 +239,7 @@ // ex_data functions. // -// These functions are wrappers. See |ex_data.h| for details. +// These functions are wrappers. See `ex_data.h` for details. OPENSSL_EXPORT int EC_KEY_get_ex_new_index(long argl, void *argp, CRYPTO_EX_unused *unused, @@ -266,7 +266,7 @@ int (*init)(EC_KEY *key); int (*finish)(EC_KEY *key); - // sign matches the arguments and behaviour of |ECDSA_sign|. + // sign matches the arguments and behaviour of `ECDSA_sign`. int (*sign)(const uint8_t *digest, size_t digest_len, uint8_t *sig, unsigned int *sig_len, EC_KEY *eckey); @@ -280,62 +280,62 @@ OPENSSL_EXPORT void EC_KEY_set_asn1_flag(EC_KEY *key, int flag); // d2i_ECPrivateKey parses a DER-encoded ECPrivateKey structure (RFC 5915) from -// |len| bytes at |*inp|, as described in |d2i_SAMPLE|. On input, if |*out_key| +// `len` bytes at `*inp`, as described in `d2i_SAMPLE`. On input, if `*out_key` // is non-NULL and has a group configured, the parameters field may be omitted // but must match that group if present. // -// Use |EC_KEY_parse_private_key| instead. +// Use `EC_KEY_parse_private_key` instead. OPENSSL_EXPORT EC_KEY *d2i_ECPrivateKey(EC_KEY **out_key, const uint8_t **inp, long len); -// i2d_ECPrivateKey marshals |key| as a DER-encoded ECPrivateKey structure (RFC -// 5915), as described in |i2d_SAMPLE|. +// i2d_ECPrivateKey marshals `key` as a DER-encoded ECPrivateKey structure (RFC +// 5915), as described in `i2d_SAMPLE`. // -// Use |EC_KEY_marshal_private_key| instead. +// Use `EC_KEY_marshal_private_key` instead. OPENSSL_EXPORT int i2d_ECPrivateKey(const EC_KEY *key, uint8_t **outp); // d2i_ECPKParameters parses a DER-encoded ECParameters structure (RFC 5480) -// from |len| bytes at |*inp|, as described in |d2i_SAMPLE|. For legacy reasons, +// from `len` bytes at `*inp`, as described in `d2i_SAMPLE`. For legacy reasons, // it recognizes the specifiedCurve form, but only for curves that are already // supported as named curves. // -// Use |EC_KEY_parse_parameters| or |EC_KEY_parse_curve_name| instead. +// Use `EC_KEY_parse_parameters` or `EC_KEY_parse_curve_name` instead. OPENSSL_EXPORT EC_GROUP *d2i_ECPKParameters(EC_GROUP **out, const uint8_t **inp, long len); -// i2d_ECPKParameters marshals |group| as a DER-encoded ECParameters structure -// (RFC 5480), as described in |i2d_SAMPLE|. +// i2d_ECPKParameters marshals `group` as a DER-encoded ECParameters structure +// (RFC 5480), as described in `i2d_SAMPLE`. // -// Use |EC_KEY_marshal_curve_name| instead. +// Use `EC_KEY_marshal_curve_name` instead. OPENSSL_EXPORT int i2d_ECPKParameters(const EC_GROUP *group, uint8_t **outp); // d2i_ECParameters parses a DER-encoded ECParameters structure (RFC 5480) from -// |len| bytes at |*inp|, as described in |d2i_SAMPLE|. It returns the result as -// an |EC_KEY| with parameters, but no key, configured. +// `len` bytes at `*inp`, as described in `d2i_SAMPLE`. It returns the result as +// an `EC_KEY` with parameters, but no key, configured. // -// Use |EC_KEY_parse_parameters| or |EC_KEY_parse_curve_name| instead. +// Use `EC_KEY_parse_parameters` or `EC_KEY_parse_curve_name` instead. OPENSSL_EXPORT EC_KEY *d2i_ECParameters(EC_KEY **out_key, const uint8_t **inp, long len); -// i2d_ECParameters marshals |key|'s parameters as a DER-encoded OBJECT -// IDENTIFIER, as described in |i2d_SAMPLE|. +// i2d_ECParameters marshals `key`'s parameters as a DER-encoded OBJECT +// IDENTIFIER, as described in `i2d_SAMPLE`. // -// Use |EC_KEY_marshal_curve_name| instead. +// Use `EC_KEY_marshal_curve_name` instead. OPENSSL_EXPORT int i2d_ECParameters(const EC_KEY *key, uint8_t **outp); -// o2i_ECPublicKey parses an EC point from |len| bytes at |*inp| into -// |*out_key|. Note that this differs from the d2i format in that |*out_key| -// must be non-NULL with a group set. On successful exit, |*inp| is advanced by -// |len| bytes. It returns |*out_key| or NULL on error. +// o2i_ECPublicKey parses an EC point from `len` bytes at `*inp` into +// `*out_key`. Note that this differs from the d2i format in that `*out_key` +// must be non-NULL with a group set. On successful exit, `*inp` is advanced by +// `len` bytes. It returns `*out_key` or NULL on error. // -// Use |EC_POINT_oct2point| instead. +// Use `EC_POINT_oct2point` instead. OPENSSL_EXPORT EC_KEY *o2i_ECPublicKey(EC_KEY **out_key, const uint8_t **inp, long len); -// i2o_ECPublicKey marshals an EC point from |key|, as described in -// |i2d_SAMPLE|, except it returns zero on error instead of a negative value. +// i2o_ECPublicKey marshals an EC point from `key`, as described in +// `i2d_SAMPLE`, except it returns zero on error instead of a negative value. // -// Use |EC_POINT_point2cbb| instead. +// Use `EC_POINT_point2cbb` instead. OPENSSL_EXPORT int i2o_ECPublicKey(const EC_KEY *key, unsigned char **outp);
diff --git a/include/openssl/ecdh.h b/include/openssl/ecdh.h index 35a99e6..a1dff7b 100644 --- a/include/openssl/ecdh.h +++ b/include/openssl/ecdh.h
@@ -28,22 +28,22 @@ // Elliptic curve Diffie-Hellman. -// ECDH_compute_key calculates the shared key between |pub_key| and |priv_key|. -// If |kdf| is not NULL, then it is called with the bytes of the shared key and -// the parameter |out|. When |kdf| returns, the value of |*outlen| becomes the +// ECDH_compute_key calculates the shared key between `pub_key` and `priv_key`. +// If `kdf` is not NULL, then it is called with the bytes of the shared key and +// the parameter `out`. When `kdf` returns, the value of `*outlen` becomes the // return value. Otherwise, as many bytes of the shared key as will fit are -// copied directly to, at most, |outlen| bytes at |out|. It returns the number -// of bytes written to |out|, or -1 on error. +// copied directly to, at most, `outlen` bytes at `out`. It returns the number +// of bytes written to `out`, or -1 on error. OPENSSL_EXPORT int ECDH_compute_key( void *out, size_t outlen, const EC_POINT *pub_key, const EC_KEY *priv_key, void *(*kdf)(const void *in, size_t inlen, void *out, size_t *outlen)); -// ECDH_compute_key_fips calculates the shared key between |pub_key| and -// |priv_key| and hashes it with the appropriate SHA function for |out_len|. The -// only value values for |out_len| are thus 24 (SHA-224), 32 (SHA-256), 48 +// ECDH_compute_key_fips calculates the shared key between `pub_key` and +// `priv_key` and hashes it with the appropriate SHA function for `out_len`. The +// only value values for `out_len` are thus 24 (SHA-224), 32 (SHA-256), 48 // (SHA-384), and 64 (SHA-512). It returns one on success and zero on error. // -// Note that the return value is different to |ECDH_compute_key|: it returns an +// Note that the return value is different to `ECDH_compute_key`: it returns an // error flag (as is common for BoringSSL) rather than the number of bytes // written. //
diff --git a/include/openssl/ecdsa.h b/include/openssl/ecdsa.h index 3eee16f..5eee809 100644 --- a/include/openssl/ecdsa.h +++ b/include/openssl/ecdsa.h
@@ -36,24 +36,24 @@ // format is variable-length. Callers must be prepared to receive signatures // that are slightly shorter than the maximum for the ECDSA curve. -// ECDSA_sign signs |digest_len| bytes from |digest| with |key| and writes the -// resulting ASN.1-based signature to |sig|, which must have |ECDSA_size(key)| -// bytes of space. On successful exit, |*sig_len| is set to the actual number of -// bytes written. The |type| argument should be zero. It returns one on success +// ECDSA_sign signs `digest_len` bytes from `digest` with `key` and writes the +// resulting ASN.1-based signature to `sig`, which must have `ECDSA_size(key)` +// bytes of space. On successful exit, `*sig_len` is set to the actual number of +// bytes written. The `type` argument should be zero. It returns one on success // and zero otherwise. // -// WARNING: |digest| must be the output of some hash function on the data to be +// WARNING: `digest` must be the output of some hash function on the data to be // signed. Passing unhashed inputs will not result in a secure signature scheme. OPENSSL_EXPORT int ECDSA_sign(int type, const uint8_t *digest, size_t digest_len, uint8_t *sig, unsigned int *sig_len, const EC_KEY *key); -// ECDSA_verify verifies that |sig_len| bytes from |sig| constitute a valid -// ASN.1-based signature by |key| of |digest|. (The |type| argument should be +// ECDSA_verify verifies that `sig_len` bytes from `sig` constitute a valid +// ASN.1-based signature by `key` of `digest`. (The `type` argument should be // zero.) It returns one on success or zero if the signature is invalid or an // error occurred. // -// WARNING: |digest| must be the output of some hash function on the data to be +// WARNING: `digest` must be the output of some hash function on the data to be // verified. Passing unhashed inputs will not result in a secure signature // scheme. OPENSSL_EXPORT int ECDSA_verify(int type, const uint8_t *digest, @@ -61,13 +61,13 @@ size_t sig_len, const EC_KEY *key); // ECDSA_size returns the maximum size of an ASN.1-based ECDSA signature using -// |key|. It returns zero if |key| is NULL or if it doesn't have a group set. +// `key`. It returns zero if `key` is NULL or if it doesn't have a group set. OPENSSL_EXPORT size_t ECDSA_size(const EC_KEY *key); // Low-level signing and verification. // -// Low-level functions handle signatures as |ECDSA_SIG| structures which allow +// Low-level functions handle signatures as `ECDSA_SIG` structures which allow // the two values in an ECDSA signature to be handled separately. struct ecdsa_sig_st { @@ -75,41 +75,41 @@ BIGNUM *s; }; -// ECDSA_SIG_new returns a fresh |ECDSA_SIG| structure or NULL on error. +// ECDSA_SIG_new returns a fresh `ECDSA_SIG` structure or NULL on error. OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_new(void); -// ECDSA_SIG_free frees |sig| its member |BIGNUM|s. +// ECDSA_SIG_free frees `sig` its member `BIGNUM`s. OPENSSL_EXPORT void ECDSA_SIG_free(ECDSA_SIG *sig); -// ECDSA_SIG_get0_r returns the r component of |sig|. +// ECDSA_SIG_get0_r returns the r component of `sig`. OPENSSL_EXPORT const BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig); -// ECDSA_SIG_get0_s returns the s component of |sig|. +// ECDSA_SIG_get0_s returns the s component of `sig`. OPENSSL_EXPORT const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig); -// ECDSA_SIG_get0 sets |*out_r| and |*out_s|, if non-NULL, to the two -// components of |sig|. +// ECDSA_SIG_get0 sets `*out_r` and `*out_s`, if non-NULL, to the two +// components of `sig`. OPENSSL_EXPORT void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **out_r, const BIGNUM **out_s); -// ECDSA_SIG_set0 sets |sig|'s components to |r| and |s|, neither of which may +// ECDSA_SIG_set0 sets `sig`'s components to `r` and `s`, neither of which may // be NULL. On success, it takes ownership of each argument and returns one. // Otherwise, it returns zero. OPENSSL_EXPORT int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s); -// ECDSA_do_sign signs |digest_len| bytes from |digest| with |key| and returns +// ECDSA_do_sign signs `digest_len` bytes from `digest` with `key` and returns // the resulting signature structure, or NULL on error. // -// WARNING: |digest| must be the output of some hash function on the data to be +// WARNING: `digest` must be the output of some hash function on the data to be // signed. Passing unhashed inputs will not result in a secure signature scheme. OPENSSL_EXPORT ECDSA_SIG *ECDSA_do_sign(const uint8_t *digest, size_t digest_len, const EC_KEY *key); -// ECDSA_do_verify verifies that |sig| constitutes a valid signature by |key| -// of |digest|. It returns one on success or zero if the signature is invalid +// ECDSA_do_verify verifies that `sig` constitutes a valid signature by `key` +// of `digest`. It returns one on success or zero if the signature is invalid // or on error. // -// WARNING: |digest| must be the output of some hash function on the data to be +// WARNING: `digest` must be the output of some hash function on the data to be // verified. Passing unhashed inputs will not result in a secure signature // scheme. OPENSSL_EXPORT int ECDSA_do_verify(const uint8_t *digest, size_t digest_len, @@ -118,28 +118,28 @@ // ASN.1 functions. -// ECDSA_SIG_parse parses a DER-encoded ECDSA-Sig-Value structure from |cbs| and -// advances |cbs|. It returns a newly-allocated |ECDSA_SIG| or NULL on error. +// ECDSA_SIG_parse parses a DER-encoded ECDSA-Sig-Value structure from `cbs` and +// advances `cbs`. It returns a newly-allocated `ECDSA_SIG` or NULL on error. OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_parse(CBS *cbs); -// ECDSA_SIG_from_bytes parses |in| as a DER-encoded ECDSA-Sig-Value structure. -// It returns a newly-allocated |ECDSA_SIG| structure or NULL on error. +// ECDSA_SIG_from_bytes parses `in` as a DER-encoded ECDSA-Sig-Value structure. +// It returns a newly-allocated `ECDSA_SIG` structure or NULL on error. OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_from_bytes(const uint8_t *in, size_t in_len); -// ECDSA_SIG_marshal marshals |sig| as a DER-encoded ECDSA-Sig-Value and appends -// the result to |cbb|. It returns one on success and zero on error. +// ECDSA_SIG_marshal marshals `sig` as a DER-encoded ECDSA-Sig-Value and appends +// the result to `cbb`. It returns one on success and zero on error. OPENSSL_EXPORT int ECDSA_SIG_marshal(CBB *cbb, const ECDSA_SIG *sig); -// ECDSA_SIG_to_bytes marshals |sig| as a DER-encoded ECDSA-Sig-Value and, on -// success, sets |*out_bytes| to a newly allocated buffer containing the result +// ECDSA_SIG_to_bytes marshals `sig` as a DER-encoded ECDSA-Sig-Value and, on +// success, sets `*out_bytes` to a newly allocated buffer containing the result // and returns one. Otherwise, it returns zero. The result should be freed with -// |OPENSSL_free|. +// `OPENSSL_free`. OPENSSL_EXPORT int ECDSA_SIG_to_bytes(uint8_t **out_bytes, size_t *out_len, const ECDSA_SIG *sig); // ECDSA_SIG_max_len returns the maximum length of a DER-encoded ECDSA-Sig-Value -// structure for a group whose order is represented in |order_len| bytes, or +// structure for a group whose order is represented in `order_len` bytes, or // zero on overflow. OPENSSL_EXPORT size_t ECDSA_SIG_max_len(size_t order_len); @@ -153,23 +153,23 @@ // the width of the group order. This format is fixed-width, so a given ECDSA // curve's signatures will always have the same size. -// ECDSA_sign_p1363 signs |digest_len| bytes from |digest| with |key| and writes -// the resulting P1363-based signature to |sig|, which must have -// |ECDSA_size_p1363(key)| bytes of space. On successful exit, |*out_sig_len| is +// ECDSA_sign_p1363 signs `digest_len` bytes from `digest` with `key` and writes +// the resulting P1363-based signature to `sig`, which must have +// `ECDSA_size_p1363(key)` bytes of space. On successful exit, `*out_sig_len` is // set to the actual number of bytes written, which will always match -// |ECDSA_size_p1363(key)|. It returns one on success and zero otherwise. +// `ECDSA_size_p1363(key)`. It returns one on success and zero otherwise. // -// WARNING: |digest| must be the output of some hash function on the data to be +// WARNING: `digest` must be the output of some hash function on the data to be // signed. Passing unhashed inputs will not result in a secure signature scheme. OPENSSL_EXPORT int ECDSA_sign_p1363(const uint8_t *digest, size_t digest_len, uint8_t *sig, size_t *out_sig_len, size_t max_sig_len, const EC_KEY *key); -// ECDSA_verify_p1363 verifies that |sig_len| bytes from |sig| constitute a -// valid P1363-based signature by |key| of |digest|. It returns one on success +// ECDSA_verify_p1363 verifies that `sig_len` bytes from `sig` constitute a +// valid P1363-based signature by `key` of `digest`. It returns one on success // or zero if the signature is invalid or an error occurred. // -// WARNING: |digest| must be the output of some hash function on the data to be +// WARNING: `digest` must be the output of some hash function on the data to be // verified. Passing unhashed inputs will not result in a secure signature // scheme. OPENSSL_EXPORT int ECDSA_verify_p1363(const uint8_t *digest, size_t digest_len, @@ -177,16 +177,16 @@ const EC_KEY *key); // ECDSA_size_p1363 returns the size of a P1363-based ECDSA signature using -// |key|. It returns zero if |key| is NULL or if it doesn't have a group set. +// `key`. It returns zero if `key` is NULL or if it doesn't have a group set. OPENSSL_EXPORT size_t ECDSA_size_p1363(const EC_KEY *key); // Testing-only functions. // ECDSA_sign_with_nonce_and_leak_private_key_for_testing behaves like -// |ECDSA_do_sign| but uses |nonce| for the ECDSA nonce 'k', instead of a random -// value. |nonce| is interpreted as a big-endian integer. It must be reduced -// modulo the group order and padded with zeros up to |BN_num_bytes(order)| +// `ECDSA_do_sign` but uses `nonce` for the ECDSA nonce 'k', instead of a random +// value. `nonce` is interpreted as a big-endian integer. It must be reduced +// modulo the group order and padded with zeros up to `BN_num_bytes(order)` // bytes. // // WARNING: This function is only exported for testing purposes, when using test @@ -202,17 +202,17 @@ // Deprecated functions. -// d2i_ECDSA_SIG parses aa DER-encoded ECDSA-Sig-Value structure from |len| -// bytes at |*inp|, as described in |d2i_SAMPLE|. +// d2i_ECDSA_SIG parses aa DER-encoded ECDSA-Sig-Value structure from `len` +// bytes at `*inp`, as described in `d2i_SAMPLE`. // -// Use |ECDSA_SIG_parse| instead. +// Use `ECDSA_SIG_parse` instead. OPENSSL_EXPORT ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **out, const uint8_t **inp, long len); -// i2d_ECDSA_SIG marshals |sig| as a DER-encoded ECDSA-Sig-Value, as described -// in |i2d_SAMPLE|. +// i2d_ECDSA_SIG marshals `sig` as a DER-encoded ECDSA-Sig-Value, as described +// in `i2d_SAMPLE`. // -// Use |ECDSA_SIG_marshal| instead. +// Use `ECDSA_SIG_marshal` instead. OPENSSL_EXPORT int i2d_ECDSA_SIG(const ECDSA_SIG *sig, uint8_t **outp);
diff --git a/include/openssl/engine.h b/include/openssl/engine.h index 6765c28..3c2dd5e 100644 --- a/include/openssl/engine.h +++ b/include/openssl/engine.h
@@ -27,9 +27,9 @@ // be overridden via a callback. This can be used, for example, to implement an // RSA* that forwards operations to a hardware module. // -// Methods are reference counted but |ENGINE|s are not. When creating a method, +// Methods are reference counted but `ENGINE`s are not. When creating a method, // you should zero the whole structure and fill in the function pointers that -// you wish before setting it on an |ENGINE|. Any functions pointers that +// you wish before setting it on an `ENGINE`. Any functions pointers that // are NULL indicate that the default behaviour should be used. @@ -40,7 +40,7 @@ OPENSSL_EXPORT ENGINE *ENGINE_new(void); // ENGINE_free decrements the reference counts for all methods linked from -// |engine| and frees |engine| itself. It returns one. +// `engine` and frees `engine` itself. It returns one. OPENSSL_EXPORT int ENGINE_free(ENGINE *engine); @@ -69,11 +69,11 @@ // These functions take a void* type but actually operate on all method // structures. -// METHOD_ref increments the reference count of |method|. This is a no-op for +// METHOD_ref increments the reference count of `method`. This is a no-op for // now because all methods are currently static. void METHOD_ref(void *method); -// METHOD_unref decrements the reference count of |method| and frees it if the +// METHOD_unref decrements the reference count of `method` and frees it if the // reference count drops to zero. This is a no-op for now because all methods // are currently static. void METHOD_unref(void *method);
diff --git a/include/openssl/err.h b/include/openssl/err.h index c7923fe..7b94af4 100644 --- a/include/openssl/err.h +++ b/include/openssl/err.h
@@ -48,20 +48,20 @@ // Reading and formatting errors. // ERR_GET_LIB returns the library code for the error. This is one of -// the |ERR_LIB_*| values. +// the `ERR_LIB_*` values. OPENSSL_INLINE int ERR_GET_LIB(uint32_t packed_error) { return (int)((packed_error >> 24) & 0xff); } // ERR_GET_REASON returns the reason code for the error. This is one of -// library-specific |LIB_R_*| values where |LIB| is the library (see -// |ERR_GET_LIB|). Note that reason codes are specific to the library. +// library-specific `LIB_R_*` values where `LIB` is the library (see +// `ERR_GET_LIB`). Note that reason codes are specific to the library. OPENSSL_INLINE int ERR_GET_REASON(uint32_t packed_error) { return (int)(packed_error & 0xfff); } -// ERR_equals returns one if |packed_error|'s library and reason code are |lib| -// and |reason|, respectively, and zero otherwise. +// ERR_equals returns one if `packed_error`'s library and reason code are `lib` +// and `reason`, respectively, and zero otherwise. OPENSSL_INLINE int ERR_equals(uint32_t packed_error, int lib, int reason) { return ERR_GET_LIB(packed_error) == lib && ERR_GET_REASON(packed_error) == reason; @@ -72,33 +72,33 @@ // it returns zero. OPENSSL_EXPORT uint32_t ERR_get_error(void); -// ERR_get_error_line acts like |ERR_get_error|, except that the file and line +// ERR_get_error_line acts like `ERR_get_error`, except that the file and line // number of the call that added the error are also returned. OPENSSL_EXPORT uint32_t ERR_get_error_line(const char **file, int *line); -// ERR_FLAG_STRING means that the |data| member is a NUL-terminated string that -// can be printed. This is always set if |data| is non-NULL. +// ERR_FLAG_STRING means that the `data` member is a NUL-terminated string that +// can be printed. This is always set if `data` is non-NULL. #define ERR_FLAG_STRING 1 -// ERR_FLAG_MALLOCED is passed into |ERR_set_error_data| to indicate that |data| -// was allocated with |OPENSSL_malloc|. +// ERR_FLAG_MALLOCED is passed into `ERR_set_error_data` to indicate that `data` +// was allocated with `OPENSSL_malloc`. // -// It is, separately, returned in |*flags| from |ERR_get_error_line_data| to -// indicate that |*data| has a non-static lifetime, but this lifetime is still -// managed by the library. The caller must not call |OPENSSL_free| or |free| on -// |data|. +// It is, separately, returned in `*flags` from `ERR_get_error_line_data` to +// indicate that `*data` has a non-static lifetime, but this lifetime is still +// managed by the library. The caller must not call `OPENSSL_free` or `free` on +// `data`. #define ERR_FLAG_MALLOCED 2 -// ERR_get_error_line_data acts like |ERR_get_error_line|, but also returns the +// ERR_get_error_line_data acts like `ERR_get_error_line`, but also returns the // error-specific data pointer and flags. The flags are a bitwise-OR of -// |ERR_FLAG_*| values. The error-specific data is owned by the error queue +// `ERR_FLAG_*` values. The error-specific data is owned by the error queue // and the pointer becomes invalid after the next call that affects the same -// thread's error queue. If |*flags| contains |ERR_FLAG_STRING| then |*data| is +// thread's error queue. If `*flags` contains `ERR_FLAG_STRING` then `*data` is // human-readable. OPENSSL_EXPORT uint32_t ERR_get_error_line_data(const char **file, int *line, const char **data, int *flags); -// The "peek" functions act like the |ERR_get_error| functions, above, but they +// The "peek" functions act like the `ERR_get_error` functions, above, but they // do not remove the error from the queue. OPENSSL_EXPORT uint32_t ERR_peek_error(void); OPENSSL_EXPORT uint32_t ERR_peek_error_line(const char **file, int *line); @@ -115,9 +115,9 @@ int *flags); // ERR_error_string_n generates a human-readable string representing -// |packed_error|, places it at |buf|, and returns |buf|. It writes at most -// |len| bytes (including the terminating NUL) and truncates the string if -// necessary. If |len| is greater than zero then |buf| is always NUL terminated. +// `packed_error`, places it at `buf`, and returns `buf`. It writes at most +// `len` bytes (including the terminating NUL) and truncates the string if +// necessary. If `len` is greater than zero then `buf` is always NUL terminated. // // The string will have the following format: // @@ -129,31 +129,31 @@ size_t len); // ERR_lib_error_string returns a string representation of the library that -// generated |packed_error|, or a placeholder string is the library is +// generated `packed_error`, or a placeholder string is the library is // unrecognized. OPENSSL_EXPORT const char *ERR_lib_error_string(uint32_t packed_error); // ERR_reason_error_string returns a string representation of the reason for -// |packed_error|, or a placeholder string if the reason is unrecognized. +// `packed_error`, or a placeholder string if the reason is unrecognized. OPENSSL_EXPORT const char *ERR_reason_error_string(uint32_t packed_error); // ERR_lib_symbol_name returns the symbol name of library that generated -// |packed_error|, or NULL if unrecognized. For example, an error from -// |ERR_LIB_EVP| would return "EVP". +// `packed_error`, or NULL if unrecognized. For example, an error from +// `ERR_LIB_EVP` would return "EVP". OPENSSL_EXPORT const char *ERR_lib_symbol_name(uint32_t packed_error); // ERR_reason_symbol_name returns the symbol name of the reason for -// |packed_error|, or NULL if unrecognized. For example, |ERR_R_INTERNAL_ERROR| +// `packed_error`, or NULL if unrecognized. For example, `ERR_R_INTERNAL_ERROR` // would return "INTERNAL_ERROR". // -// Errors from the |ERR_LIB_SYS| library are typically |errno| values and will +// Errors from the `ERR_LIB_SYS` library are typically `errno` values and will // return NULL. User-defined errors will also return NULL. OPENSSL_EXPORT const char *ERR_reason_symbol_name(uint32_t packed_error); // ERR_print_errors_callback_t is the type of a function used by -// |ERR_print_errors_cb|. It takes a pointer to a human readable string (and -// its length) that describes an entry in the error queue. The |ctx| argument -// is an opaque pointer given to |ERR_print_errors_cb|. +// `ERR_print_errors_cb`. It takes a pointer to a human readable string (and +// its length) that describes an entry in the error queue. The `ctx` argument +// is an opaque pointer given to `ERR_print_errors_cb`. // // It should return one on success or zero on error, which will stop the // iteration over the error queue. @@ -161,22 +161,22 @@ void *ctx); // ERR_print_errors_cb clears the current thread's error queue, calling -// |callback| with a string representation of each error, from the least recent +// `callback` with a string representation of each error, from the least recent // to the most recent error. // // The string will have the following format (which differs from -// |ERR_error_string|): +// `ERR_error_string`): // // [thread id]:error:[error code]:[library name]:OPENSSL_internal:[reason string]:[file]:[line number]:[optional string data] // // The callback can return one to continue the iteration or zero to stop it. -// The |ctx| argument is an opaque value that is passed through to the +// The `ctx` argument is an opaque value that is passed through to the // callback. OPENSSL_EXPORT void ERR_print_errors_cb(ERR_print_errors_callback_t callback, void *ctx); // ERR_print_errors_fp clears the current thread's error queue, printing each -// error to |file|. See |ERR_print_errors_cb| for the format. +// error to `file`. See `ERR_print_errors_cb` for the format. OPENSSL_EXPORT void ERR_print_errors_fp(FILE *file); @@ -185,21 +185,21 @@ // ERR_clear_error clears the error queue for the current thread. OPENSSL_EXPORT void ERR_clear_error(void); -// ERR_set_mark "marks" the most recent error for use with |ERR_pop_to_mark|. +// ERR_set_mark "marks" the most recent error for use with `ERR_pop_to_mark`. // It returns one if an error was marked and zero if there are no errors. OPENSSL_EXPORT int ERR_set_mark(void); // ERR_pop_to_mark removes errors from the most recent to the least recent // until (and not including) a "marked" error. It returns zero if no marked // error was found (and thus all errors were removed) and one otherwise. Errors -// are marked using |ERR_set_mark|. +// are marked using `ERR_set_mark`. OPENSSL_EXPORT int ERR_pop_to_mark(void); // Custom errors. // ERR_get_next_error_library returns a value suitable for passing as the -// |library| argument to |ERR_put_error|. This is intended for code that wishes +// `library` argument to `ERR_put_error`. This is intended for code that wishes // to push its own, non-standard errors to the error queue. OPENSSL_EXPORT int ERR_get_next_error_library(void); @@ -312,29 +312,29 @@ // ERR_free_strings does nothing. OPENSSL_EXPORT void ERR_free_strings(void); -// ERR_remove_state calls |ERR_clear_error|. +// ERR_remove_state calls `ERR_clear_error`. OPENSSL_EXPORT void ERR_remove_state(unsigned long pid); // ERR_remove_thread_state clears the error queue for the current thread if -// |tid| is NULL. Otherwise it calls |assert(0)|, because it's no longer +// `tid` is NULL. Otherwise it calls `assert(0)`, because it's no longer // possible to delete the error queue for other threads. // -// Use |ERR_clear_error| instead. Note error queues are deleted automatically on +// Use `ERR_clear_error` instead. Note error queues are deleted automatically on // thread exit. You do not need to call this function to release memory. OPENSSL_EXPORT void ERR_remove_thread_state(const CRYPTO_THREADID *tid); // ERR_func_error_string returns the string "OPENSSL_internal". OPENSSL_EXPORT const char *ERR_func_error_string(uint32_t packed_error); -// ERR_error_string behaves like |ERR_error_string_n| but |len| is implicitly -// |ERR_ERROR_STRING_BUF_LEN|. +// ERR_error_string behaves like `ERR_error_string_n` but `len` is implicitly +// `ERR_ERROR_STRING_BUF_LEN`. // -// Additionally, if |buf| is NULL, the error string is placed in a static buffer +// Additionally, if `buf` is NULL, the error string is placed in a static buffer // which is returned. This is not thread-safe and only exists for backwards // compatibility with legacy callers. The static buffer will be overridden by // calls in other threads. // -// Use |ERR_error_string_n| instead. +// Use `ERR_error_string_n` instead. // // TODO(fork): remove this function. OPENSSL_EXPORT char *ERR_error_string(uint32_t packed_error, char *buf); @@ -373,7 +373,7 @@ OPENSSL_EXPORT void ERR_put_error(int library, int unused, int reason, const char *file, unsigned line); -// ERR_add_error_data takes a variable number (|count|) of const char* +// ERR_add_error_data takes a variable number (`count`) of const char* // pointers, concatenates them and sets the result as the data on the most // recent error. OPENSSL_EXPORT void ERR_add_error_data(unsigned count, ...); @@ -383,13 +383,13 @@ OPENSSL_EXPORT void ERR_add_error_dataf(const char *format, ...) OPENSSL_PRINTF_FORMAT_FUNC(1, 2); -// ERR_set_error_data sets the data on the most recent error to |data|, which -// must be a NUL-terminated string. |flags| must contain |ERR_FLAG_STRING|. If -// |flags| contains |ERR_FLAG_MALLOCED|, this function takes ownership of -// |data|, which must have been allocated with |OPENSSL_malloc|. Otherwise, it -// saves a copy of |data|. +// ERR_set_error_data sets the data on the most recent error to `data`, which +// must be a NUL-terminated string. `flags` must contain `ERR_FLAG_STRING`. If +// `flags` contains `ERR_FLAG_MALLOCED`, this function takes ownership of +// `data`, which must have been allocated with `OPENSSL_malloc`. Otherwise, it +// saves a copy of `data`. // -// Note this differs from OpenSSL which, when |ERR_FLAG_MALLOCED| is unset, +// Note this differs from OpenSSL which, when `ERR_FLAG_MALLOCED` is unset, // saves the pointer as-is and requires it remain valid for the lifetime of the // address space. OPENSSL_EXPORT void ERR_set_error_data(char *data, int flags); @@ -404,7 +404,7 @@ // OPENSSL_DECLARE_ERROR_REASON is used by util/make_errors.h (which generates // the error defines) to recognise that an additional reason value is needed. // This is needed when the reason value is used outside of an -// |OPENSSL_PUT_ERROR| macro. The resulting define will be +// `OPENSSL_PUT_ERROR` macro. The resulting define will be // ${lib}_R_${reason}. #define OPENSSL_DECLARE_ERROR_REASON(lib, reason)
diff --git a/include/openssl/evp.h b/include/openssl/evp.h index bb168db..bcfcdc1 100644 --- a/include/openssl/evp.h +++ b/include/openssl/evp.h
@@ -37,80 +37,80 @@ // Public/private key objects. // -// An |EVP_PKEY| object represents a public or private key. A given object may +// An `EVP_PKEY` object represents a public or private key. A given object may // be used concurrently on multiple threads by non-mutating functions, provided // no other thread is concurrently calling a mutating function. Unless otherwise -// documented, functions which take a |const| pointer are non-mutating and -// functions which take a non-|const| pointer are mutating. +// documented, functions which take a `const` pointer are non-mutating and +// functions which take a non-`const` pointer are mutating. // EVP_PKEY_new creates a new, empty public-key object and returns it or NULL // on allocation failure. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_new(void); -// EVP_PKEY_free decrements the reference count of |pkey| and frees it if the +// EVP_PKEY_free decrements the reference count of `pkey` and frees it if the // reference count drops to zero. OPENSSL_EXPORT void EVP_PKEY_free(EVP_PKEY *pkey); -// EVP_PKEY_up_ref increments the reference count of |pkey| and returns one. It -// does not mutate |pkey| for thread-safety purposes and may be used +// EVP_PKEY_up_ref increments the reference count of `pkey` and returns one. It +// does not mutate `pkey` for thread-safety purposes and may be used // concurrently. OPENSSL_EXPORT int EVP_PKEY_up_ref(EVP_PKEY *pkey); -// EVP_PKEY_dup_ref increments the reference count of |pkey| and returns |pkey|. -// The caller must call |EVP_PKEY_free| on the result to release the reference. +// EVP_PKEY_dup_ref increments the reference count of `pkey` and returns `pkey`. +// The caller must call `EVP_PKEY_free` on the result to release the reference. // -// WARNING: Although the result is non-const for use with |EVP_PKEY_free|, it is +// WARNING: Although the result is non-const for use with `EVP_PKEY_free`, it is // still shared with other parts of the application that share the same object. -// Avoid mutating shared |EVP_PKEY|s. +// Avoid mutating shared `EVP_PKEY`s. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_dup_ref(const EVP_PKEY *pkey); -// EVP_PKEY_is_opaque returns one if |pkey| is opaque. Opaque keys are backed by +// EVP_PKEY_is_opaque returns one if `pkey` is opaque. Opaque keys are backed by // custom implementations which do not expose key material and parameters. It is // an error to attempt to duplicate, export, or compare an opaque key. OPENSSL_EXPORT int EVP_PKEY_is_opaque(const EVP_PKEY *pkey); -// EVP_PKEY_eq compares |a| and |b| and returns one if their public keys are +// EVP_PKEY_eq compares `a` and `b` and returns one if their public keys are // equal and zero otherwise. OPENSSL_EXPORT int EVP_PKEY_eq(const EVP_PKEY *a, const EVP_PKEY *b); -// EVP_PKEY_copy_parameters sets the parameters of |to| to equal the parameters -// of |from|. It returns one on success and zero on error. +// EVP_PKEY_copy_parameters sets the parameters of `to` to equal the parameters +// of `from`. It returns one on success and zero on error. OPENSSL_EXPORT int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); -// EVP_PKEY_missing_parameters returns one if |pkey| is missing needed +// EVP_PKEY_missing_parameters returns one if `pkey` is missing needed // parameters or zero if not, or if the algorithm doesn't take parameters. OPENSSL_EXPORT int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); -// EVP_PKEY_parameters_eq compares the parameters of |a| and |b|. It returns one +// EVP_PKEY_parameters_eq compares the parameters of `a` and `b`. It returns one // if they match and zero otherwise. In algorithms that do not use parameters, // this function returns one; null parameters are vacuously equal. OPENSSL_EXPORT int EVP_PKEY_parameters_eq(const EVP_PKEY *a, const EVP_PKEY *b); // EVP_PKEY_size returns the maximum size, in bytes, of a signature signed by -// |pkey|. For an RSA key, this returns the number of bytes needed to represent +// `pkey`. For an RSA key, this returns the number of bytes needed to represent // the modulus. For an EC key, this returns the maximum size of a DER-encoded // ECDSA signature. OPENSSL_EXPORT int EVP_PKEY_size(const EVP_PKEY *pkey); -// EVP_PKEY_bits returns the "size", in bits, of |pkey|. For an RSA key, this +// EVP_PKEY_bits returns the "size", in bits, of `pkey`. For an RSA key, this // returns the bit length of the modulus. For an EC key, this returns the bit // length of the group order. OPENSSL_EXPORT int EVP_PKEY_bits(const EVP_PKEY *pkey); -// EVP_PKEY_has_public returns one if |pkey| has a public key, or zero +// EVP_PKEY_has_public returns one if `pkey` has a public key, or zero // otherwise. OPENSSL_EXPORT int EVP_PKEY_has_public(const EVP_PKEY *pkey); -// EVP_PKEY_has_private returns one if |pkey| has a private key, or zero +// EVP_PKEY_has_private returns one if `pkey` has a private key, or zero // otherwise. OPENSSL_EXPORT int EVP_PKEY_has_private(const EVP_PKEY *pkey); -// EVP_PKEY_copy_public returns a newly-allocated |EVP_PKEY| that contains only -// the public key of |pkey|, or NULL on error. Parameters, if relevant for the +// EVP_PKEY_copy_public returns a newly-allocated `EVP_PKEY` that contains only +// the public key of `pkey`, or NULL on error. Parameters, if relevant for the // key type, are also copied. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_copy_public(const EVP_PKEY *pkey); -// The following constants are returned by |EVP_PKEY_id| and specify the type of +// The following constants are returned by `EVP_PKEY_id` and specify the type of // key. #define EVP_PKEY_NONE NID_undef #define EVP_PKEY_RSA NID_rsaEncryption @@ -128,81 +128,81 @@ #define EVP_PKEY_ML_KEM_1024 NID_ML_KEM_1024 #define EVP_PKEY_XWING NID_X_Wing -// EVP_PKEY_id returns the type of |pkey|, which is one of the |EVP_PKEY_*| +// EVP_PKEY_id returns the type of `pkey`, which is one of the `EVP_PKEY_*` // values above. These type values generally correspond to the algorithm OID, // but not the parameters, of a SubjectPublicKeyInfo (RFC 5280) or // PrivateKeyInfo (RFC 5208) AlgorithmIdentifier. Algorithm parameters can be // inspected with algorithm-specific accessors, e.g. -// |EVP_PKEY_get_ec_curve_nid|. +// `EVP_PKEY_get_ec_curve_nid`. OPENSSL_EXPORT int EVP_PKEY_id(const EVP_PKEY *pkey); // Algorithms. // -// An |EVP_PKEY| may carry a key from one of several algorithms, represented by -// |EVP_PKEY_ALG|. |EVP_PKEY_ALG|s are used by functions that construct -// |EVP_PKEY|s, such as parsing, so that callers can specify the algorithm(s) to +// An `EVP_PKEY` may carry a key from one of several algorithms, represented by +// `EVP_PKEY_ALG`. `EVP_PKEY_ALG`s are used by functions that construct +// `EVP_PKEY`s, such as parsing, so that callers can specify the algorithm(s) to // use. // -// Each |EVP_PKEY_ALG| generally corresponds to the AlgorithmIdentifier of a +// Each `EVP_PKEY_ALG` generally corresponds to the AlgorithmIdentifier of a // SubjectPublicKeyInfo (RFC 5280) or PrivateKeyInfo (RFC 5208), but some may // support multiple sets of AlgorithmIdentifier parameters, while others may be // specific to one parameter. // EVP_pkey_rsa implements RSA keys (RFC 8017), encoded as rsaEncryption (RFC // 3279, Section 2.3.1). The rsaEncryption encoding is confusingly named: these -// keys are used for all RSA operations, including signing. The |EVP_PKEY_id| -// value is |EVP_PKEY_RSA|. +// keys are used for all RSA operations, including signing. The `EVP_PKEY_id` +// value is `EVP_PKEY_RSA`. // -// WARNING: This |EVP_PKEY_ALG| accepts all RSA key sizes supported by +// WARNING: This `EVP_PKEY_ALG` accepts all RSA key sizes supported by // BoringSSL. When parsing RSA keys, callers should check the size is within -// their desired bounds with |EVP_PKEY_bits|. RSA public key operations scale +// their desired bounds with `EVP_PKEY_bits`. RSA public key operations scale // quadratically and RSA private key operations scale cubicly, so key sizes may // be a DoS vector. OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_rsa(void); // EVP_pkey_ec_* implement EC keys, encoded as id-ecPublicKey (RFC 5480, // Section 2.1.1). The id-ecPublicKey encoding is confusingly named: it is also -// used for private keys (RFC 5915). The |EVP_PKEY_id| value is |EVP_PKEY_EC|. +// used for private keys (RFC 5915). The `EVP_PKEY_id` value is `EVP_PKEY_EC`. // // Each function only supports the specified curve, but curves are not reflected -// in |EVP_PKEY_id|. The curve can be inspected with -// |EVP_PKEY_get_ec_curve_nid|. +// in `EVP_PKEY_id`. The curve can be inspected with +// `EVP_PKEY_get_ec_curve_nid`. OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_ec_p224(void); OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_ec_p256(void); OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_ec_p384(void); OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_ec_p521(void); // EVP_pkey_x25519 implements X25519 keys (RFC 7748), encoded as in RFC 8410. -// The |EVP_PKEY_id| value is |EVP_PKEY_X25519|. +// The `EVP_PKEY_id` value is `EVP_PKEY_X25519`. OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_x25519(void); // EVP_pkey_ed25519 implements Ed25519 keys (RFC 8032), encoded as in RFC 8410. -// The |EVP_PKEY_id| value is |EVP_PKEY_ED25519|. +// The `EVP_PKEY_id` value is `EVP_PKEY_ED25519`. OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_ed25519(void); // EVP_pkey_ml_dsa_* implement ML-DSA keys, encoded as in -// draft-ietf-lamps-dilithium-certificates. The |EVP_PKEY_id| values are -// |EVP_PKEY_ML_DSA_*|. In the private key representation, only the "seed" form +// draft-ietf-lamps-dilithium-certificates. The `EVP_PKEY_id` values are +// `EVP_PKEY_ML_DSA_*`. In the private key representation, only the "seed" form // is serialized or parsed. // // To configure OpenSSL to output the standard "seed" form, configure the // "ml-dsa.output_formats" provider parameter so that "seed-only" is first. This // can be done programmatically with OpenSSL's -// |OSSL_PROVIDER_add_conf_parameter| function, or by passing "-provparam" to +// `OSSL_PROVIDER_add_conf_parameter` function, or by passing "-provparam" to // the command-line tool. OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_ml_dsa_44(void); OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_ml_dsa_65(void); OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_ml_dsa_87(void); // EVP_pkey_ml_kem_* implement ML-KEM keys, encoded as in RFC 9935. The -// |EVP_PKEY_id| values are |EVP_PKEY_ML_KEM_*|. In the private key +// `EVP_PKEY_id` values are `EVP_PKEY_ML_KEM_*`. In the private key // representation, only the "seed" form is serialized or parsed. // // To configure OpenSSL to output the standard "seed" form, configure the // "ml-kem.output_formats" provider parameter so that "seed-only" is first. This // can be done programmatically with OpenSSL's -// |OSSL_PROVIDER_add_conf_parameter| function, or by passing "-provparam" to +// `OSSL_PROVIDER_add_conf_parameter` function, or by passing "-provparam" to // the command-line tool. OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_ml_kem_768(void); OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_ml_kem_1024(void); @@ -214,22 +214,22 @@ OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_xwing(void); // EVP_pkey_dsa implements DSA keys, encoded as in RFC 3279, Section 2.3.2. The -// |EVP_PKEY_id| value is |EVP_PKEY_DSA|. This |EVP_PKEY_ALG| accepts all DSA +// `EVP_PKEY_id` value is `EVP_PKEY_DSA`. This `EVP_PKEY_ALG` accepts all DSA // parameters supported by BoringSSL. // // Keys of this type are not usable with any operations, though the underlying -// |DSA| object can be extracted with |EVP_PKEY_get0_DSA|. This key type is +// `DSA` object can be extracted with `EVP_PKEY_get0_DSA`. This key type is // deprecated and only implemented for compatibility with legacy applications. // -// TODO(crbug.com/42290364): We didn't wire up |EVP_PKEY_sign| and -// |EVP_PKEY_verify| just so it was auditable which callers used DSA. Once DSA +// TODO(crbug.com/42290364): We didn't wire up `EVP_PKEY_sign` and +// `EVP_PKEY_verify` just so it was auditable which callers used DSA. Once DSA // is removed from the default SPKI and PKCS#8 parser and DSA users explicitly -// request |EVP_pkey_dsa|, we could change that. +// request `EVP_pkey_dsa`, we could change that. OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_dsa(void); // EVP_pkey_rsa_pss_* implements RSASSA-PSS keys, encoded as id-RSASSA-PSS -// (RFC 4055, Section 3.1). The |EVP_PKEY_id| value is |EVP_PKEY_RSA_PSS|. Each -// |EVP_PKEY_ALG| only accepts keys whose parameters specify: +// (RFC 4055, Section 3.1). The `EVP_PKEY_id` value is `EVP_PKEY_RSA_PSS`. Each +// `EVP_PKEY_ALG` only accepts keys whose parameters specify: // // - A hashAlgorithm of the specified hash // - A maskGenAlgorithm of MGF1 with the specified hash @@ -248,18 +248,18 @@ // parameters chosen. // // Note the id-RSASSA-PSS key type is distinct from the RSASSA-PSS signature -// algorithm. The widely implemented id-rsaEncryption key type (|EVP_pkey_rsa| -// and |EVP_PKEY_RSA|) also supports RSASSA-PSS signatures. +// algorithm. The widely implemented id-rsaEncryption key type (`EVP_pkey_rsa` +// and `EVP_PKEY_RSA`) also supports RSASSA-PSS signatures. // -// WARNING: Any |EVP_PKEY|s produced by this algorithm will return a non-NULL -// |RSA| object through |EVP_PKEY_get1_RSA| and |EVP_PKEY_get0_RSA|. This is +// WARNING: Any `EVP_PKEY`s produced by this algorithm will return a non-NULL +// `RSA` object through `EVP_PKEY_get1_RSA` and `EVP_PKEY_get0_RSA`. This is // dangerous as existing code may assume a non-NULL return implies the more // common id-rsaEncryption key. Additionally, the operations on the underlying -// |RSA| object will not capture the RSA-PSS constraints, so callers risk +// `RSA` object will not capture the RSA-PSS constraints, so callers risk // misusing the key by calling these functions. Callers using this algorithm -// must use |EVP_PKEY_id| to distinguish |EVP_PKEY_RSA| and |EVP_PKEY_RSA_PSS|. +// must use `EVP_PKEY_id` to distinguish `EVP_PKEY_RSA` and `EVP_PKEY_RSA_PSS`. // -// WARNING: BoringSSL does not currently implement |RSA_get0_pss_params| with +// WARNING: BoringSSL does not currently implement `RSA_get0_pss_params` with // these keys. Callers that require this functionality should contact the // BoringSSL team. OPENSSL_EXPORT const EVP_PKEY_ALG *EVP_pkey_rsa_pss_sha256(void); @@ -270,29 +270,29 @@ // Getting and setting concrete key types. // // The following functions get and set the underlying key representation in an -// |EVP_PKEY| object. The |set1| functions take an additional reference to the -// underlying key and return one on success or zero if |key| is NULL. The -// |assign| functions adopt the caller's reference and return one on success or -// zero if |key| is NULL. The |get1| functions return a fresh reference to the -// underlying object or NULL if |pkey| is not of the correct type. The |get0| +// `EVP_PKEY` object. The `set1` functions take an additional reference to the +// underlying key and return one on success or zero if `key` is NULL. The +// `assign` functions adopt the caller's reference and return one on success or +// zero if `key` is NULL. The `get1` functions return a fresh reference to the +// underlying object or NULL if `pkey` is not of the correct type. The `get0` // functions behave the same but return a non-owning pointer. // -// The |get0| and |get1| functions take |const| pointers and are thus +// The `get0` and `get1` functions take `const` pointers and are thus // non-mutating for thread-safety purposes, but mutating functions on the -// returned lower-level objects are considered to also mutate the |EVP_PKEY| and -// may not be called concurrently with other operations on the |EVP_PKEY|. +// returned lower-level objects are considered to also mutate the `EVP_PKEY` and +// may not be called concurrently with other operations on the `EVP_PKEY`. // // WARNING: Matching OpenSSL, the RSA functions behave non-uniformly. -// |EVP_PKEY_set1_RSA| and |EVP_PKEY_assign_RSA| construct an |EVP_PKEY_RSA| -// key, while the |EVP_PKEY_get0_RSA| and |EVP_PKEY_get1_RSA| will return -// non-NULL for both |EVP_PKEY_RSA| and |EVP_PKEY_RSA_PSS|. +// `EVP_PKEY_set1_RSA` and `EVP_PKEY_assign_RSA` construct an `EVP_PKEY_RSA` +// key, while the `EVP_PKEY_get0_RSA` and `EVP_PKEY_get1_RSA` will return +// non-NULL for both `EVP_PKEY_RSA` and `EVP_PKEY_RSA_PSS`. // // This means callers risk misusing a key if they assume a non-NULL return from -// |EVP_PKEY_get0_RSA| or |EVP_PKEY_get1_RSA| implies |EVP_PKEY_RSA|. Prefer -// |EVP_PKEY_id| to check the type of a key. To reduce this risk, BoringSSL does -// not make |EVP_PKEY_RSA_PSS| available by default, only when callers opt in -// via |EVP_pkey_rsa_pss_sha256|. This differs from upstream OpenSSL, where -// callers are exposed to |EVP_PKEY_RSA_PSS| by default. +// `EVP_PKEY_get0_RSA` or `EVP_PKEY_get1_RSA` implies `EVP_PKEY_RSA`. Prefer +// `EVP_PKEY_id` to check the type of a key. To reduce this risk, BoringSSL does +// not make `EVP_PKEY_RSA_PSS` available by default, only when callers opt in +// via `EVP_pkey_rsa_pss_sha256`. This differs from upstream OpenSSL, where +// callers are exposed to `EVP_PKEY_RSA_PSS` by default. OPENSSL_EXPORT int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key); OPENSSL_EXPORT int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key); @@ -318,21 +318,21 @@ // ASN.1 functions // EVP_PKEY_from_subject_public_key_info decodes a DER-encoded -// SubjectPublicKeyInfo structure (RFC 5280) from |in|. It returns a -// newly-allocated |EVP_PKEY| or NULL on error. Only the |num_algs| algorithms -// in |algs| will be considered when parsing. +// SubjectPublicKeyInfo structure (RFC 5280) from `in`. It returns a +// newly-allocated `EVP_PKEY` or NULL on error. Only the `num_algs` algorithms +// in `algs` will be considered when parsing. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_from_subject_public_key_info( const uint8_t *in, size_t len, const EVP_PKEY_ALG *const *algs, size_t num_algs); // EVP_parse_public_key decodes a DER-encoded SubjectPublicKeyInfo structure -// (RFC 5280) from |cbs| and advances |cbs|. It returns a newly-allocated -// |EVP_PKEY| or NULL on error. +// (RFC 5280) from `cbs` and advances `cbs`. It returns a newly-allocated +// `EVP_PKEY` or NULL on error. // -// Prefer |EVP_PKEY_from_subject_public_key_info| instead. This function has +// Prefer `EVP_PKEY_from_subject_public_key_info` instead. This function has // several pitfalls: // -// Callers are expected to handle trailing data returned from |cbs|, making more +// Callers are expected to handle trailing data returned from `cbs`, making more // common cases error-prone. // // There is also no way to pass in supported algorithms. This function instead @@ -346,14 +346,14 @@ // size or EC curve. OPENSSL_EXPORT EVP_PKEY *EVP_parse_public_key(CBS *cbs); -// EVP_marshal_public_key marshals |key| as a DER-encoded SubjectPublicKeyInfo -// structure (RFC 5280) and appends the result to |cbb|. It returns one on +// EVP_marshal_public_key marshals `key` as a DER-encoded SubjectPublicKeyInfo +// structure (RFC 5280) and appends the result to `cbb`. It returns one on // success and zero on error. OPENSSL_EXPORT int EVP_marshal_public_key(CBB *cbb, const EVP_PKEY *key); // EVP_PKEY_from_private_key_info decodes a DER-encoded PrivateKeyInfo structure -// (RFC 5208) from |in|. It returns a newly-allocated |EVP_PKEY| or NULL on -// error. Only the |num_algs| algorithms in |algs| will be considered when +// (RFC 5208) from `in`. It returns a newly-allocated `EVP_PKEY` or NULL on +// error. Only the `num_algs` algorithms in `algs` will be considered when // parsing. // // A PrivateKeyInfo ends with an optional set of attributes. These are silently @@ -363,13 +363,13 @@ size_t num_algs); // EVP_parse_private_key decodes a DER-encoded PrivateKeyInfo structure (RFC -// 5208) from |cbs| and advances |cbs|. It returns a newly-allocated |EVP_PKEY| +// 5208) from `cbs` and advances `cbs`. It returns a newly-allocated `EVP_PKEY` // or NULL on error. // -// Prefer |EVP_PKEY_from_private_key_info| instead. This function has +// Prefer `EVP_PKEY_from_private_key_info` instead. This function has // several pitfalls: // -// Callers are expected to handle trailing data returned from |cbs|, making more +// Callers are expected to handle trailing data returned from `cbs`, making more // common cases error-prone. // // There is also no way to pass in supported algorithms. This function instead @@ -382,14 +382,14 @@ // it is suitable and validate other desired key properties such as RSA modulus // size or EC curve. In particular, RSA private key operations scale cubicly, so // applications accepting RSA private keys from external sources may need to -// bound key sizes (use |EVP_PKEY_bits| or |RSA_bits|) to avoid a DoS vector. +// bound key sizes (use `EVP_PKEY_bits` or `RSA_bits`) to avoid a DoS vector. // // A PrivateKeyInfo ends with an optional set of attributes. These are silently // ignored. OPENSSL_EXPORT EVP_PKEY *EVP_parse_private_key(CBS *cbs); -// EVP_marshal_private_key marshals |key| as a DER-encoded PrivateKeyInfo -// structure (RFC 5208) and appends the result to |cbb|. It returns one on +// EVP_marshal_private_key marshals `key` as a DER-encoded PrivateKeyInfo +// structure (RFC 5208) and appends the result to `cbb`. It returns one on // success and zero on error. OPENSSL_EXPORT int EVP_marshal_private_key(CBB *cbb, const EVP_PKEY *key); @@ -402,14 +402,14 @@ // - X25519, using the formats in RFC 7748. // // - Ed25519, using the formats in RFC 8032. Note the RFC 8032 private key -// format is the 32-byte prefix of |ED25519_sign|'s 64-byte private key. +// format is the 32-byte prefix of `ED25519_sign`'s 64-byte private key. // // - ML-DSA, using the formats in FIPS 204. The private key representation // supported by BoringSSL is the 32-byte "seed", defined in FIPS 204 as 𝜉, not // the larger expanded form. For OpenSSL compatibility, it is not used with -// the |EVP_PKEY_from_raw_private_key| and |EVP_PKEY_get_raw_private_key| -// APIs, but instead the |EVP_PKEY_from_private_seed| and -// |EVP_PKEY_get_private_seed| APIs. +// the `EVP_PKEY_from_raw_private_key` and `EVP_PKEY_get_raw_private_key` +// APIs, but instead the `EVP_PKEY_from_private_seed` and +// `EVP_PKEY_get_private_seed` APIs. // // - ML-KEM, using the formats in FIPS 203. The private key representation // supported by BoringSSL is the 64-byte "seed" resulting from the @@ -418,50 +418,50 @@ // These formats are suitable if serializing a key in a context where the // algorithm is already known and there is no need to encode it. -// EVP_PKEY_from_raw_private_key interprets |in| as a raw private key of type -// |alg| and returns a newly-allocated |EVP_PKEY|, or nullptr on error. +// EVP_PKEY_from_raw_private_key interprets `in` as a raw private key of type +// `alg` and returns a newly-allocated `EVP_PKEY`, or nullptr on error. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_from_raw_private_key(const EVP_PKEY_ALG *alg, const uint8_t *in, size_t len); -// EVP_PKEY_from_private_seed interprets |in| as a private seed of type |alg| -// and returns a newly-allocated |EVP_PKEY|, or nullptr on error. +// EVP_PKEY_from_private_seed interprets `in` as a private seed of type `alg` +// and returns a newly-allocated `EVP_PKEY`, or nullptr on error. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_from_private_seed(const EVP_PKEY_ALG *alg, const uint8_t *in, size_t len); -// EVP_PKEY_from_raw_public_key interprets |in| as a raw public key of type -// |alg| and returns a newly-allocated |EVP_PKEY|, or nullptr on error. +// EVP_PKEY_from_raw_public_key interprets `in` as a raw public key of type +// `alg` and returns a newly-allocated `EVP_PKEY`, or nullptr on error. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_from_raw_public_key(const EVP_PKEY_ALG *alg, const uint8_t *in, size_t len); -// EVP_PKEY_get_raw_private_key outputs the private key for |pkey| in raw form. -// If |out| is NULL, it sets |*out_len| to the size of the raw private key. -// Otherwise, it writes at most |*out_len| bytes to |out| and sets |*out_len| to +// EVP_PKEY_get_raw_private_key outputs the private key for `pkey` in raw form. +// If `out` is NULL, it sets `*out_len` to the size of the raw private key. +// Otherwise, it writes at most `*out_len` bytes to `out` and sets `*out_len` to // the number of bytes written. // -// It returns one on success and zero if |pkey| has no private key, the key +// It returns one on success and zero if `pkey` has no private key, the key // type does not support this format, or the buffer is too small. OPENSSL_EXPORT int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, uint8_t *out, size_t *out_len); -// EVP_PKEY_get_private_seed outputs the private key for |pkey| as a private -// seed. If |out| is NULL, it sets |*out_len| to the size of the seed. -// Otherwise, it writes at most |*out_len| bytes to |out| and sets -// |*out_len| to the number of bytes written. +// EVP_PKEY_get_private_seed outputs the private key for `pkey` as a private +// seed. If `out` is NULL, it sets `*out_len` to the size of the seed. +// Otherwise, it writes at most `*out_len` bytes to `out` and sets +// `*out_len` to the number of bytes written. // -// It returns one on success and zero if |pkey| has no private key, the key +// It returns one on success and zero if `pkey` has no private key, the key // type does not support this format, or the buffer is too small. OPENSSL_EXPORT int EVP_PKEY_get_private_seed(const EVP_PKEY *pkey, uint8_t *out, size_t *out_len); -// EVP_PKEY_get_raw_public_key outputs the public key for |pkey| in raw form. -// If |out| is NULL, it sets |*out_len| to the size of the raw public key. -// Otherwise, it writes at most |*out_len| bytes to |out| and sets |*out_len| to +// EVP_PKEY_get_raw_public_key outputs the public key for `pkey` in raw form. +// If `out` is NULL, it sets `*out_len` to the size of the raw public key. +// Otherwise, it writes at most `*out_len` bytes to `out` and sets `*out_len` to // the number of bytes written. // -// It returns one on success and zero if |pkey| has no public key, the key +// It returns one on success and zero if `pkey` has no public key, the key // type does not support this format, or the buffer is too small. OPENSSL_EXPORT int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, uint8_t *out, size_t *out_len); @@ -469,64 +469,64 @@ // Key generation -// EVP_PKEY_generate_from_alg generates a new key of type |alg|. It returns a -// newly-allocated |EVP_PKEY| or nullptr on error. +// EVP_PKEY_generate_from_alg generates a new key of type `alg`. It returns a +// newly-allocated `EVP_PKEY` or nullptr on error. // -// When passed |EVP_pkey_rsa|, this function generates an RSA-2048 key with the -// recommended public exponent of 65537, or |RSA_F4|. Use |EVP_RSA_gen| or -// |EVP_PKEY_keygen| instead to customize these parameters. +// When passed `EVP_pkey_rsa`, this function generates an RSA-2048 key with the +// recommended public exponent of 65537, or `RSA_F4`. Use `EVP_RSA_gen` or +// `EVP_PKEY_keygen` instead to customize these parameters. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_generate_from_alg(const EVP_PKEY_ALG *alg); // Signing -// EVP_DigestSignInit sets up |ctx| for a signing operation with |type| and -// |pkey|. The |ctx| argument must have been initialised with -// |EVP_MD_CTX_init|. If |pctx| is not NULL, the |EVP_PKEY_CTX| of the signing -// operation will be written to |*pctx|; this can be used to set alternative +// EVP_DigestSignInit sets up `ctx` for a signing operation with `type` and +// `pkey`. The `ctx` argument must have been initialised with +// `EVP_MD_CTX_init`. If `pctx` is not NULL, the `EVP_PKEY_CTX` of the signing +// operation will be written to `*pctx`; this can be used to set alternative // signing options. // // For single-shot signing algorithms which do not use a pre-hash, such as -// Ed25519, |type| should be NULL. The |EVP_MD_CTX| itself is unused but is -// present so the API is uniform. See |EVP_DigestSign|. +// Ed25519, `type` should be NULL. The `EVP_MD_CTX` itself is unused but is +// present so the API is uniform. See `EVP_DigestSign`. // -// This function does not mutate |pkey| for thread-safety purposes and may be -// used concurrently with other non-mutating functions on |pkey|. +// This function does not mutate `pkey` for thread-safety purposes and may be +// used concurrently with other non-mutating functions on `pkey`. // // It returns one on success, or zero on error. OPENSSL_EXPORT int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); -// EVP_DigestSignUpdate appends |len| bytes from |data| to the data which will -// be signed in |EVP_DigestSignFinal|. It returns one. +// EVP_DigestSignUpdate appends `len` bytes from `data` to the data which will +// be signed in `EVP_DigestSignFinal`. It returns one. // // This function performs a streaming signing operation and will fail for -// signature algorithms which do not support this. Use |EVP_DigestSign| for a +// signature algorithms which do not support this. Use `EVP_DigestSign` for a // single-shot operation. OPENSSL_EXPORT int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *data, size_t len); // EVP_DigestSignFinal signs the data that has been included by one or more -// calls to |EVP_DigestSignUpdate|. If |out_sig| is NULL then |*out_sig_len| is +// calls to `EVP_DigestSignUpdate`. If `out_sig` is NULL then `*out_sig_len` is // set to the maximum number of output bytes. Otherwise, on entry, -// |*out_sig_len| must contain the length of the |out_sig| buffer. If the call -// is successful, the signature is written to |out_sig| and |*out_sig_len| is +// `*out_sig_len` must contain the length of the `out_sig` buffer. If the call +// is successful, the signature is written to `out_sig` and `*out_sig_len` is // set to its length. // // This function performs a streaming signing operation and will fail for -// signature algorithms which do not support this. Use |EVP_DigestSign| for a +// signature algorithms which do not support this. Use `EVP_DigestSign` for a // single-shot operation. // // It returns one on success, or zero on error. OPENSSL_EXPORT int EVP_DigestSignFinal(EVP_MD_CTX *ctx, uint8_t *out_sig, size_t *out_sig_len); -// EVP_DigestSign signs |data_len| bytes from |data| using |ctx|. If |out_sig| -// is NULL then |*out_sig_len| is set to the maximum number of output -// bytes. Otherwise, on entry, |*out_sig_len| must contain the length of the -// |out_sig| buffer. If the call is successful, the signature is written to -// |out_sig| and |*out_sig_len| is set to its length. +// EVP_DigestSign signs `data_len` bytes from `data` using `ctx`. If `out_sig` +// is NULL then `*out_sig_len` is set to the maximum number of output +// bytes. Otherwise, on entry, `*out_sig_len` must contain the length of the +// `out_sig` buffer. If the call is successful, the signature is written to +// `out_sig` and `*out_sig_len` is set to its length. // // It returns one on success and zero on error. OPENSSL_EXPORT int EVP_DigestSign(EVP_MD_CTX *ctx, uint8_t *out_sig, @@ -536,45 +536,45 @@ // Verifying -// EVP_DigestVerifyInit sets up |ctx| for a signature verification operation -// with |type| and |pkey|. The |ctx| argument must have been initialised with -// |EVP_MD_CTX_init|. If |pctx| is not NULL, the |EVP_PKEY_CTX| of the signing -// operation will be written to |*pctx|; this can be used to set alternative +// EVP_DigestVerifyInit sets up `ctx` for a signature verification operation +// with `type` and `pkey`. The `ctx` argument must have been initialised with +// `EVP_MD_CTX_init`. If `pctx` is not NULL, the `EVP_PKEY_CTX` of the signing +// operation will be written to `*pctx`; this can be used to set alternative // signing options. // // For single-shot signing algorithms which do not use a pre-hash, such as -// Ed25519, |type| should be NULL. The |EVP_MD_CTX| itself is unused but is -// present so the API is uniform. See |EVP_DigestVerify|. +// Ed25519, `type` should be NULL. The `EVP_MD_CTX` itself is unused but is +// present so the API is uniform. See `EVP_DigestVerify`. // -// This function does not mutate |pkey| for thread-safety purposes and may be -// used concurrently with other non-mutating functions on |pkey|. +// This function does not mutate `pkey` for thread-safety purposes and may be +// used concurrently with other non-mutating functions on `pkey`. // // It returns one on success, or zero on error. OPENSSL_EXPORT int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); -// EVP_DigestVerifyUpdate appends |len| bytes from |data| to the data which -// will be verified by |EVP_DigestVerifyFinal|. It returns one. +// EVP_DigestVerifyUpdate appends `len` bytes from `data` to the data which +// will be verified by `EVP_DigestVerifyFinal`. It returns one. // // This function performs streaming signature verification and will fail for -// signature algorithms which do not support this. Use |EVP_DigestVerify| for a +// signature algorithms which do not support this. Use `EVP_DigestVerify` for a // single-shot verification. OPENSSL_EXPORT int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *data, size_t len); -// EVP_DigestVerifyFinal verifies that |sig_len| bytes of |sig| are a valid +// EVP_DigestVerifyFinal verifies that `sig_len` bytes of `sig` are a valid // signature for the data that has been included by one or more calls to -// |EVP_DigestVerifyUpdate|. It returns one on success and zero otherwise. +// `EVP_DigestVerifyUpdate`. It returns one on success and zero otherwise. // // This function performs streaming signature verification and will fail for -// signature algorithms which do not support this. Use |EVP_DigestVerify| for a +// signature algorithms which do not support this. Use `EVP_DigestVerify` for a // single-shot verification. OPENSSL_EXPORT int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const uint8_t *sig, size_t sig_len); -// EVP_DigestVerify verifies that |sig_len| bytes from |sig| are a valid -// signature for |data|. It returns one on success or zero on error. +// EVP_DigestVerify verifies that `sig_len` bytes from `sig` are a valid +// signature for `data`. It returns one on success or zero on error. OPENSSL_EXPORT int EVP_DigestVerify(EVP_MD_CTX *ctx, const uint8_t *sig, size_t sig_len, const uint8_t *data, size_t len); @@ -582,71 +582,71 @@ // Signing (old functions) -// EVP_SignInit_ex configures |ctx|, which must already have been initialised, -// for a fresh signing operation using the hash function |type|. It returns one +// EVP_SignInit_ex configures `ctx`, which must already have been initialised, +// for a fresh signing operation using the hash function `type`. It returns one // on success and zero otherwise. // -// (In order to initialise |ctx|, either obtain it initialised with -// |EVP_MD_CTX_create|, or use |EVP_MD_CTX_init|.) +// (In order to initialise `ctx`, either obtain it initialised with +// `EVP_MD_CTX_create`, or use `EVP_MD_CTX_init`.) OPENSSL_EXPORT int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); -// EVP_SignInit is a deprecated version of |EVP_SignInit_ex|. +// EVP_SignInit is a deprecated version of `EVP_SignInit_ex`. // // TODO(fork): remove. OPENSSL_EXPORT int EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); -// EVP_SignUpdate appends |len| bytes from |data| to the data which will be -// signed in |EVP_SignFinal|. +// EVP_SignUpdate appends `len` bytes from `data` to the data which will be +// signed in `EVP_SignFinal`. OPENSSL_EXPORT int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *data, size_t len); // EVP_SignFinal signs the data that has been included by one or more calls to -// |EVP_SignUpdate|, using the key |pkey|, and writes it to |sig|. On entry, -// |sig| must point to at least |EVP_PKEY_size(pkey)| bytes of space. The -// actual size of the signature is written to |*out_sig_len|. +// `EVP_SignUpdate`, using the key `pkey`, and writes it to `sig`. On entry, +// `sig` must point to at least `EVP_PKEY_size(pkey)` bytes of space. The +// actual size of the signature is written to `*out_sig_len`. // // It returns one on success and zero otherwise. // -// It does not modify |ctx|, thus it's possible to continue to use |ctx| in -// order to sign a longer message. It also does not mutate |pkey| for +// It does not modify `ctx`, thus it's possible to continue to use `ctx` in +// order to sign a longer message. It also does not mutate `pkey` for // thread-safety purposes and may be used concurrently with other non-mutating -// functions on |pkey|. +// functions on `pkey`. OPENSSL_EXPORT int EVP_SignFinal(const EVP_MD_CTX *ctx, uint8_t *sig, unsigned int *out_sig_len, EVP_PKEY *pkey); // Verifying (old functions) -// EVP_VerifyInit_ex configures |ctx|, which must already have been +// EVP_VerifyInit_ex configures `ctx`, which must already have been // initialised, for a fresh signature verification operation using the hash -// function |type|. It returns one on success and zero otherwise. +// function `type`. It returns one on success and zero otherwise. // -// (In order to initialise |ctx|, either obtain it initialised with -// |EVP_MD_CTX_create|, or use |EVP_MD_CTX_init|.) +// (In order to initialise `ctx`, either obtain it initialised with +// `EVP_MD_CTX_create`, or use `EVP_MD_CTX_init`.) OPENSSL_EXPORT int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); -// EVP_VerifyInit is a deprecated version of |EVP_VerifyInit_ex|. +// EVP_VerifyInit is a deprecated version of `EVP_VerifyInit_ex`. // // TODO(fork): remove. OPENSSL_EXPORT int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); -// EVP_VerifyUpdate appends |len| bytes from |data| to the data which will be -// signed in |EVP_VerifyFinal|. +// EVP_VerifyUpdate appends `len` bytes from `data` to the data which will be +// signed in `EVP_VerifyFinal`. OPENSSL_EXPORT int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *data, size_t len); -// EVP_VerifyFinal verifies that |sig_len| bytes of |sig| are a valid -// signature, by |pkey|, for the data that has been included by one or more -// calls to |EVP_VerifyUpdate|. +// EVP_VerifyFinal verifies that `sig_len` bytes of `sig` are a valid +// signature, by `pkey`, for the data that has been included by one or more +// calls to `EVP_VerifyUpdate`. // // It returns one on success and zero otherwise. // -// It does not modify |ctx|, thus it's possible to continue to use |ctx| in -// order to verify a longer message. It also does not mutate |pkey| for +// It does not modify `ctx`, thus it's possible to continue to use `ctx` in +// order to verify a longer message. It also does not mutate `pkey` for // thread-safety purposes and may be used concurrently with other non-mutating -// functions on |pkey|. +// functions on `pkey`. OPENSSL_EXPORT int EVP_VerifyFinal(EVP_MD_CTX *ctx, const uint8_t *sig, size_t sig_len, EVP_PKEY *pkey); @@ -654,17 +654,17 @@ // Printing // EVP_PKEY_print_public prints a textual representation of the public key in -// |pkey| to |out|. Returns one on success or zero otherwise. +// `pkey` to `out`. Returns one on success or zero otherwise. OPENSSL_EXPORT int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey, int indent, ASN1_PCTX *pctx); // EVP_PKEY_print_private prints a textual representation of the private key in -// |pkey| to |out|. Returns one on success or zero otherwise. +// `pkey` to `out`. Returns one on success or zero otherwise. OPENSSL_EXPORT int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey, int indent, ASN1_PCTX *pctx); // EVP_PKEY_print_params prints a textual representation of the parameters in -// |pkey| to |out|. Returns one on success or zero otherwise. +// `pkey` to `out`. Returns one on success or zero otherwise. OPENSSL_EXPORT int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey, int indent, ASN1_PCTX *pctx); @@ -675,38 +675,38 @@ // function that results in a key suitable for use in symmetric // cryptography. -// PKCS5_PBKDF2_HMAC computes |iterations| iterations of PBKDF2 of |password| -// and |salt|, using |digest|, and outputs |key_len| bytes to |out_key|. It +// PKCS5_PBKDF2_HMAC computes `iterations` iterations of PBKDF2 of `password` +// and `salt`, using `digest`, and outputs `key_len` bytes to `out_key`. It // returns one on success and zero on allocation failure or if iterations is 0. OPENSSL_EXPORT int PKCS5_PBKDF2_HMAC(const char *password, size_t password_len, const uint8_t *salt, size_t salt_len, uint32_t iterations, const EVP_MD *digest, size_t key_len, uint8_t *out_key); -// PKCS5_PBKDF2_HMAC_SHA1 is the same as PKCS5_PBKDF2_HMAC, but with |digest| -// fixed to |EVP_sha1|. +// PKCS5_PBKDF2_HMAC_SHA1 is the same as PKCS5_PBKDF2_HMAC, but with `digest` +// fixed to `EVP_sha1`. OPENSSL_EXPORT int PKCS5_PBKDF2_HMAC_SHA1(const char *password, size_t password_len, const uint8_t *salt, size_t salt_len, uint32_t iterations, size_t key_len, uint8_t *out_key); -// EVP_PBE_scrypt expands |password| into a secret key of length |key_len| using -// scrypt, as described in RFC 7914, and writes the result to |out_key|. It +// EVP_PBE_scrypt expands `password` into a secret key of length `key_len` using +// scrypt, as described in RFC 7914, and writes the result to `out_key`. It // returns one on success and zero on allocation failure, if the memory required -// for the operation exceeds |max_mem|, or if any of the parameters are invalid +// for the operation exceeds `max_mem`, or if any of the parameters are invalid // as described below. // -// |N|, |r|, and |p| are as described in RFC 7914 section 6. They determine the -// cost of the operation. If |max_mem| is zero, a default limit of 65MiB will be +// `N`, `r`, and `p` are as described in RFC 7914 section 6. They determine the +// cost of the operation. If `max_mem` is zero, a default limit of 65MiB will be // used. // // The parameters are considered invalid under any of the following conditions: -// - |r| or |p| are zero -// - |p| > (2^30 - 1) / |r| -// - |N| is not a power of two -// - |N| > 2^32 -// - |N| > 2^(128 * |r| / 8) +// - `r` or `p` are zero +// - `p` > (2^30 - 1) / `r` +// - `N` is not a power of two +// - `N` > 2^32 +// - `N` > 2^(128 * `r` / 8) OPENSSL_EXPORT int EVP_PBE_scrypt(const char *password, size_t password_len, const uint8_t *salt, size_t salt_len, uint64_t N, uint64_t r, uint64_t p, @@ -716,72 +716,72 @@ // Operations. // -// |EVP_PKEY_CTX| objects hold the context for an operation (e.g. signing or -// encrypting) that uses an |EVP_PKEY|. They are used to configure +// `EVP_PKEY_CTX` objects hold the context for an operation (e.g. signing or +// encrypting) that uses an `EVP_PKEY`. They are used to configure // algorithm-specific parameters for the operation before performing the // operation. The general pattern for performing an operation in EVP is: // -// 1. Construct an |EVP_PKEY_CTX|, either with |EVP_PKEY_CTX_new| (operations -// using a key, like signing) or |EVP_PKEY_CTX_new_id| (operations not using +// 1. Construct an `EVP_PKEY_CTX`, either with `EVP_PKEY_CTX_new` (operations +// using a key, like signing) or `EVP_PKEY_CTX_new_id` (operations not using // an existing key, like key generation). // -// 2. Initialize it for an operation. For example, |EVP_PKEY_sign_init| -// initializes an |EVP_PKEY_CTX| for signing. +// 2. Initialize it for an operation. For example, `EVP_PKEY_sign_init` +// initializes an `EVP_PKEY_CTX` for signing. // // 3. Configure algorithm-specific parameters for the operation by calling -// control functions on the |EVP_PKEY_CTX|. Some functions are generic, such -// as |EVP_PKEY_CTX_set_signature_md|, and some are specific to an algorithm, -// such as |EVP_PKEY_CTX_set_rsa_padding|. +// control functions on the `EVP_PKEY_CTX`. Some functions are generic, such +// as `EVP_PKEY_CTX_set_signature_md`, and some are specific to an algorithm, +// such as `EVP_PKEY_CTX_set_rsa_padding`. // -// 4. Perform the operation. For example, |EVP_PKEY_sign| signs with the +// 4. Perform the operation. For example, `EVP_PKEY_sign` signs with the // corresponding parameters. // -// 5. Release the |EVP_PKEY_CTX| with |EVP_PKEY_CTX_free|. +// 5. Release the `EVP_PKEY_CTX` with `EVP_PKEY_CTX_free`. // -// Each |EVP_PKEY| algorithm interprets operations and parameters differently. +// Each `EVP_PKEY` algorithm interprets operations and parameters differently. // Not all algorithms support all operations. Functions will fail if the // algorithm does not support the parameter or operation. -// EVP_PKEY_CTX_new allocates a fresh |EVP_PKEY_CTX| for use with |pkey|. It +// EVP_PKEY_CTX_new allocates a fresh `EVP_PKEY_CTX` for use with `pkey`. It // returns the context or NULL on error. OPENSSL_EXPORT EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e); -// EVP_PKEY_CTX_new_id allocates a fresh |EVP_PKEY_CTX| for a key of type |id| -// (e.g. |EVP_PKEY_HMAC|). This can be used for key generation where -// |EVP_PKEY_CTX_new| can't be used because there isn't an |EVP_PKEY| to pass +// EVP_PKEY_CTX_new_id allocates a fresh `EVP_PKEY_CTX` for a key of type `id` +// (e.g. `EVP_PKEY_HMAC`). This can be used for key generation where +// `EVP_PKEY_CTX_new` can't be used because there isn't an `EVP_PKEY` to pass // it. It returns the context or NULL on error. // -// For key generation, prefer to use |EVP_PKEY_generate_from_alg|. +// For key generation, prefer to use `EVP_PKEY_generate_from_alg`. OPENSSL_EXPORT EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e); -// EVP_PKEY_CTX_free frees |ctx| and the data it owns. +// EVP_PKEY_CTX_free frees `ctx` and the data it owns. OPENSSL_EXPORT void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx); -// EVP_PKEY_CTX_dup allocates a fresh |EVP_PKEY_CTX| and sets it equal to the -// state of |ctx|. It returns the fresh |EVP_PKEY_CTX| or NULL on error. +// EVP_PKEY_CTX_dup allocates a fresh `EVP_PKEY_CTX` and sets it equal to the +// state of `ctx`. It returns the fresh `EVP_PKEY_CTX` or NULL on error. OPENSSL_EXPORT EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx); -// EVP_PKEY_CTX_get0_pkey returns the |EVP_PKEY| associated with |ctx|. +// EVP_PKEY_CTX_get0_pkey returns the `EVP_PKEY` associated with `ctx`. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_CTX_get0_pkey(EVP_PKEY_CTX *ctx); -// EVP_PKEY_sign_init initialises an |EVP_PKEY_CTX| for a signing operation. It -// should be called before |EVP_PKEY_sign|. +// EVP_PKEY_sign_init initialises an `EVP_PKEY_CTX` for a signing operation. It +// should be called before `EVP_PKEY_sign`. // // It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); -// EVP_PKEY_sign signs |digest_len| bytes from |digest| using |ctx|. If |sig| is -// NULL, the maximum size of the signature is written to |out_sig_len|. -// Otherwise, |*sig_len| must contain the number of bytes of space available at -// |sig|. If sufficient, the signature will be written to |sig| and |*sig_len| +// EVP_PKEY_sign signs `digest_len` bytes from `digest` using `ctx`. If `sig` is +// NULL, the maximum size of the signature is written to `out_sig_len`. +// Otherwise, `*sig_len` must contain the number of bytes of space available at +// `sig`. If sufficient, the signature will be written to `sig` and `*sig_len` // updated with the true length. This function will fail for signature // algorithms like Ed25519 that do not support signing pre-hashed inputs. // -// WARNING: |digest| must be the output of some hash function on the data to be +// WARNING: `digest` must be the output of some hash function on the data to be // signed. Passing unhashed inputs will not result in a secure signature scheme. -// Use |EVP_DigestSignInit| to sign an unhashed input. +// Use `EVP_DigestSignInit` to sign an unhashed input. // -// WARNING: Setting |sig| to NULL only gives the maximum size of the +// WARNING: Setting `sig` to NULL only gives the maximum size of the // signature. The actual signature may be smaller. // // It returns one on success or zero on error. (Note: this differs from @@ -790,19 +790,19 @@ size_t *sig_len, const uint8_t *digest, size_t digest_len); -// EVP_PKEY_verify_init initialises an |EVP_PKEY_CTX| for a signature -// verification operation. It should be called before |EVP_PKEY_verify|. +// EVP_PKEY_verify_init initialises an `EVP_PKEY_CTX` for a signature +// verification operation. It should be called before `EVP_PKEY_verify`. // // It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); -// EVP_PKEY_verify verifies that |sig_len| bytes from |sig| are a valid -// signature for |digest|. This function will fail for signature +// EVP_PKEY_verify verifies that `sig_len` bytes from `sig` are a valid +// signature for `digest`. This function will fail for signature // algorithms like Ed25519 that do not support signing pre-hashed inputs. // -// WARNING: |digest| must be the output of some hash function on the data to be +// WARNING: `digest` must be the output of some hash function on the data to be // verified. Passing unhashed inputs will not result in a secure signature -// scheme. Use |EVP_DigestVerifyInit| to verify a signature given the unhashed +// scheme. Use `EVP_DigestVerifyInit` to verify a signature given the unhashed // input. // // It returns one on success or zero on error. @@ -810,19 +810,19 @@ size_t sig_len, const uint8_t *digest, size_t digest_len); -// EVP_PKEY_encrypt_init initialises an |EVP_PKEY_CTX| for an encryption -// operation. It should be called before |EVP_PKEY_encrypt|. +// EVP_PKEY_encrypt_init initialises an `EVP_PKEY_CTX` for an encryption +// operation. It should be called before `EVP_PKEY_encrypt`. // // It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx); -// EVP_PKEY_encrypt encrypts |in_len| bytes from |in|. If |out| is NULL, the -// maximum size of the ciphertext is written to |out_len|. Otherwise, |*out_len| -// must contain the number of bytes of space available at |out|. If sufficient, -// the ciphertext will be written to |out| and |*out_len| updated with the true +// EVP_PKEY_encrypt encrypts `in_len` bytes from `in`. If `out` is NULL, the +// maximum size of the ciphertext is written to `out_len`. Otherwise, `*out_len` +// must contain the number of bytes of space available at `out`. If sufficient, +// the ciphertext will be written to `out` and `*out_len` updated with the true // length. // -// WARNING: Setting |out| to NULL only gives the maximum size of the +// WARNING: Setting `out` to NULL only gives the maximum size of the // ciphertext. The actual ciphertext may be smaller. // // It returns one on success or zero on error. @@ -830,19 +830,19 @@ size_t *out_len, const uint8_t *in, size_t in_len); -// EVP_PKEY_decrypt_init initialises an |EVP_PKEY_CTX| for a decryption -// operation. It should be called before |EVP_PKEY_decrypt|. +// EVP_PKEY_decrypt_init initialises an `EVP_PKEY_CTX` for a decryption +// operation. It should be called before `EVP_PKEY_decrypt`. // // It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx); -// EVP_PKEY_decrypt decrypts |in_len| bytes from |in|. If |out| is NULL, the -// maximum size of the plaintext is written to |out_len|. Otherwise, |*out_len| -// must contain the number of bytes of space available at |out|. If sufficient, -// the ciphertext will be written to |out| and |*out_len| updated with the true +// EVP_PKEY_decrypt decrypts `in_len` bytes from `in`. If `out` is NULL, the +// maximum size of the plaintext is written to `out_len`. Otherwise, `*out_len` +// must contain the number of bytes of space available at `out`. If sufficient, +// the ciphertext will be written to `out` and `*out_len` updated with the true // length. // -// WARNING: Setting |out| to NULL only gives the maximum size of the +// WARNING: Setting `out` to NULL only gives the maximum size of the // plaintext. The actual plaintext may be smaller. // // It returns one on success or zero on error. @@ -850,8 +850,8 @@ size_t *out_len, const uint8_t *in, size_t in_len); -// EVP_PKEY_verify_recover_init initialises an |EVP_PKEY_CTX| for a public-key -// decryption operation. It should be called before |EVP_PKEY_verify_recover|. +// EVP_PKEY_verify_recover_init initialises an `EVP_PKEY_CTX` for a public-key +// decryption operation. It should be called before `EVP_PKEY_verify_recover`. // // Public-key decryption is a very obscure operation that is only implemented // by RSA keys. It is effectively a signature verification operation that @@ -861,16 +861,16 @@ // It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx); -// EVP_PKEY_verify_recover decrypts |sig_len| bytes from |sig|. If |out| is -// NULL, the maximum size of the plaintext is written to |out_len|. Otherwise, -// |*out_len| must contain the number of bytes of space available at |out|. If -// sufficient, the ciphertext will be written to |out| and |*out_len| updated +// EVP_PKEY_verify_recover decrypts `sig_len` bytes from `sig`. If `out` is +// NULL, the maximum size of the plaintext is written to `out_len`. Otherwise, +// `*out_len` must contain the number of bytes of space available at `out`. If +// sufficient, the ciphertext will be written to `out` and `*out_len` updated // with the true length. // -// WARNING: Setting |out| to NULL only gives the maximum size of the +// WARNING: Setting `out` to NULL only gives the maximum size of the // plaintext. The actual plaintext may be smaller. // -// See the warning about this operation in |EVP_PKEY_verify_recover_init|. It +// See the warning about this operation in `EVP_PKEY_verify_recover_init`. It // is probably not what you want. // // It returns one on success or zero on error. @@ -878,81 +878,81 @@ size_t *out_len, const uint8_t *sig, size_t siglen); -// EVP_PKEY_derive_init initialises an |EVP_PKEY_CTX| for a key derivation -// operation. It should be called before |EVP_PKEY_derive_set_peer| and -// |EVP_PKEY_derive|. +// EVP_PKEY_derive_init initialises an `EVP_PKEY_CTX` for a key derivation +// operation. It should be called before `EVP_PKEY_derive_set_peer` and +// `EVP_PKEY_derive`. // // It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); // EVP_PKEY_derive_set_peer sets the peer's key to be used for key derivation -// by |ctx| to |peer|. It should be called after |EVP_PKEY_derive_init|. (For +// by `ctx` to `peer`. It should be called after `EVP_PKEY_derive_init`. (For // example, this is used to set the peer's key in (EC)DH.) It returns one on // success and zero on error. OPENSSL_EXPORT int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); -// EVP_PKEY_derive derives a shared key from |ctx|. If |key| is non-NULL then, -// on entry, |out_key_len| must contain the amount of space at |key|. If -// sufficient then the shared key will be written to |key| and |*out_key_len| -// will be set to the length. If |key| is NULL then |out_key_len| will be set to +// EVP_PKEY_derive derives a shared key from `ctx`. If `key` is non-NULL then, +// on entry, `out_key_len` must contain the amount of space at `key`. If +// sufficient then the shared key will be written to `key` and `*out_key_len` +// will be set to the length. If `key` is NULL then `out_key_len` will be set to // the maximum length. // -// WARNING: Setting |out| to NULL only gives the maximum size of the key. The +// WARNING: Setting `out` to NULL only gives the maximum size of the key. The // actual key may be smaller. // // It returns one on success and zero on error. OPENSSL_EXPORT int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, uint8_t *key, size_t *out_key_len); -// EVP_PKEY_keygen_init initialises an |EVP_PKEY_CTX| for a key generation -// operation. It should be called before |EVP_PKEY_keygen|. +// EVP_PKEY_keygen_init initialises an `EVP_PKEY_CTX` for a key generation +// operation. It should be called before `EVP_PKEY_keygen`. // // It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); // EVP_PKEY_keygen performs a key generation operation using the values from -// |ctx|. If |*out_pkey| is non-NULL, it overwrites |*out_pkey| with the -// resulting key. Otherwise, it sets |*out_pkey| to a newly-allocated |EVP_PKEY| +// `ctx`. If `*out_pkey` is non-NULL, it overwrites `*out_pkey` with the +// resulting key. Otherwise, it sets `*out_pkey` to a newly-allocated `EVP_PKEY` // containing the result. It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **out_pkey); -// EVP_PKEY_paramgen_init initialises an |EVP_PKEY_CTX| for a parameter -// generation operation. It should be called before |EVP_PKEY_paramgen|. +// EVP_PKEY_paramgen_init initialises an `EVP_PKEY_CTX` for a parameter +// generation operation. It should be called before `EVP_PKEY_paramgen`. // // It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); // EVP_PKEY_paramgen performs a parameter generation using the values from -// |ctx|. If |*out_pkey| is non-NULL, it overwrites |*out_pkey| with the -// resulting parameters, but no key. Otherwise, it sets |*out_pkey| to a -// newly-allocated |EVP_PKEY| containing the result. It returns one on success +// `ctx`. If `*out_pkey` is non-NULL, it overwrites `*out_pkey` with the +// resulting parameters, but no key. Otherwise, it sets `*out_pkey` to a +// newly-allocated `EVP_PKEY` containing the result. It returns one on success // or zero on error. OPENSSL_EXPORT int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **out_pkey); -// EVP_PKEY_encapsulate_init initialises an |EVP_PKEY_CTX| for an encapsulate -// operation. It should be called before |EVP_PKEY_encapsulate|. |params| is +// EVP_PKEY_encapsulate_init initialises an `EVP_PKEY_CTX` for an encapsulate +// operation. It should be called before `EVP_PKEY_encapsulate`. `params` is // included for OpenSSL compatibility, but this parameter should be NULL or have -// |OSSL_PARAM_END| as its first element. +// `OSSL_PARAM_END` as its first element. // // It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_encapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM *params); -// EVP_PKEY_encapsulate implements public key encapsulation using |ctx|. It +// EVP_PKEY_encapsulate implements public key encapsulation using `ctx`. It // either performs the operation or returns the maximum output sizes, depending -// on whether |out_ciphertext| is NULL: +// on whether `out_ciphertext` is NULL: // -// If |out_ciphertext| is NULL, it writes the maximum ciphertext length to -// |*out_ciphertext_len| and the maximum shared secret length to -// |*out_secret_len|. Either of |out_ciphertext_len| or |out_secret_len| may be +// If `out_ciphertext` is NULL, it writes the maximum ciphertext length to +// `*out_ciphertext_len` and the maximum shared secret length to +// `*out_secret_len`. Either of `out_ciphertext_len` or `out_secret_len` may be // NULL to ignore the corresponding output. // -// If |out_ciphertext| is non-NULL, it performs the operation and, on success, -// writes the ciphertext to |out_ciphertext|, the ciphertext size to -// |out_ciphertext_len|, the shared secret to |out_secret|, and the shared -// secret length to |out_secret_len|. On input, |*out_ciphertext_len| and -// |*out_secret_len| must contain the amount of space available in -// |out_ciphertext| and |out_secret|, respectively. If there is insufficient +// If `out_ciphertext` is non-NULL, it performs the operation and, on success, +// writes the ciphertext to `out_ciphertext`, the ciphertext size to +// `out_ciphertext_len`, the shared secret to `out_secret`, and the shared +// secret length to `out_secret_len`. On input, `*out_ciphertext_len` and +// `*out_secret_len` must contain the amount of space available in +// `out_ciphertext` and `out_secret`, respectively. If there is insufficient // space to write the output, the operation will fail. // // In both modes, this function returns one on success or zero on error. @@ -962,26 +962,26 @@ uint8_t *out_secret, size_t *out_secret_len); -// EVP_PKEY_decapsulate_init initialises an |EVP_PKEY_CTX| for a decapsulate -// operation. It should be called before |EVP_PKEY_decapsulate|. |params| is +// EVP_PKEY_decapsulate_init initialises an `EVP_PKEY_CTX` for a decapsulate +// operation. It should be called before `EVP_PKEY_decapsulate`. `params` is // included for OpenSSL compatibility, but this parameter should be NULL or have -// |OSSL_PARAM_END| as its first element. +// `OSSL_PARAM_END` as its first element. // // It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_decapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM *params); -// EVP_PKEY_decapsulate implements private key decapsulation using |ctx|. -// |ciphertext| and |ciphertext_len| specify the ciphertext to be decapsulated. -// If |out_secret| is NULL, it writes the maximum size of the shared secret -// output to |*out_secret_len| and returns one. Otherwise, |*out_secret_len| -// must contain the number of bytes of space available at |out_secret|. If the +// EVP_PKEY_decapsulate implements private key decapsulation using `ctx`. +// `ciphertext` and `ciphertext_len` specify the ciphertext to be decapsulated. +// If `out_secret` is NULL, it writes the maximum size of the shared secret +// output to `*out_secret_len` and returns one. Otherwise, `*out_secret_len` +// must contain the number of bytes of space available at `out_secret`. If the // space is insufficient, this function returns zero. If the space is -// sufficient, the decapsulated shared secret will be written to |out_secret| -// and the size of the output to |out_secret_len|, and this function will return -// one. If |ciphertext| has been corrupted, the function may fail or it may +// sufficient, the decapsulated shared secret will be written to `out_secret` +// and the size of the output to `out_secret_len`, and this function will return +// one. If `ciphertext` has been corrupted, the function may fail or it may // output a shared secret that appears to be random. Any subsequent symmetric -// encryption using |out_secret| must use an authenticated encryption scheme to +// encryption using `out_secret` must use an authenticated encryption scheme to // discover the decapsulation failure. OPENSSL_EXPORT int EVP_PKEY_decapsulate(EVP_PKEY_CTX *ctx, uint8_t *out_secret, size_t *out_secret_len, @@ -991,18 +991,18 @@ // Generic control functions. -// EVP_PKEY_CTX_set_signature_md sets |md| as the digest to be used in a +// EVP_PKEY_CTX_set_signature_md sets `md` as the digest to be used in a // signature operation. It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); -// EVP_PKEY_CTX_get_signature_md sets |*out_md| to the digest to be used in a +// EVP_PKEY_CTX_get_signature_md sets `*out_md` to the digest to be used in a // signature operation. It returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **out_md); // EVP_PKEY_CTX_set1_signature_context_string sets the context string for a -// signature or verification operation to |context|. It returns one success and +// signature or verification operation to `context`. It returns one success and // zero on error. The context string is an additional input to some signature // algorithms, such as ML-DSA, to separate different uses of the same key. This // is known as domain separation. Section 8.3 of RFC 8032 provides some @@ -1019,41 +1019,41 @@ // RSA specific control functions. // EVP_RSA_gen generates a new RSA key with the specified number of bits. It -// returns a newly-allocated |EVP_PKEY| or nullptr on error. +// returns a newly-allocated `EVP_PKEY` or nullptr on error. // // This function sets the public exponent to the recommended value of 65537, or -// |RSA_F4|. To use a less common value, instead use -// |EVP_PKEY_CTX_set_rsa_keygen_pubexp| and |EVP_PKEY_keygen|. +// `RSA_F4`. To use a less common value, instead use +// `EVP_PKEY_CTX_set_rsa_keygen_pubexp` and `EVP_PKEY_keygen`. OPENSSL_EXPORT EVP_PKEY *EVP_RSA_gen(unsigned bits); // EVP_PKEY_CTX_set_rsa_padding sets the padding type to use. It should be one -// of the |RSA_*_PADDING| values. Returns one on success or zero on error. By -// default, the padding is |RSA_PKCS1_PADDING|. +// of the `RSA_*_PADDING` values. Returns one on success or zero on error. By +// default, the padding is `RSA_PKCS1_PADDING`. OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int padding); -// EVP_PKEY_CTX_get_rsa_padding sets |*out_padding| to the current padding -// value, which is one of the |RSA_*_PADDING| values. Returns one on success or +// EVP_PKEY_CTX_get_rsa_padding sets `*out_padding` to the current padding +// value, which is one of the `RSA_*_PADDING` values. Returns one on success or // zero on error. OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *out_padding); // EVP_PKEY_CTX_set_rsa_pss_saltlen sets the length of the salt in a PSS-padded -// signature. A value of |RSA_PSS_SALTLEN_DIGEST| causes the salt to be the same -// length as the digest in the signature. A value of |RSA_PSS_SALTLEN_AUTO| +// signature. A value of `RSA_PSS_SALTLEN_DIGEST` causes the salt to be the same +// length as the digest in the signature. A value of `RSA_PSS_SALTLEN_AUTO` // causes the salt to be the maximum length that will fit when signing and // recovered from the signature when verifying. Otherwise the value gives the // size of the salt in bytes. // -// If unsure, use |RSA_PSS_SALTLEN_DIGEST|, which is the default. Note this -// differs from OpenSSL, which defaults to |RSA_PSS_SALTLEN_AUTO|. +// If unsure, use `RSA_PSS_SALTLEN_DIGEST`, which is the default. Note this +// differs from OpenSSL, which defaults to `RSA_PSS_SALTLEN_AUTO`. // // Returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int salt_len); -// EVP_PKEY_CTX_get_rsa_pss_saltlen sets |*out_salt_len| to the salt length of +// EVP_PKEY_CTX_get_rsa_pss_saltlen sets `*out_salt_len` to the salt length of // a PSS-padded signature. See the documentation for -// |EVP_PKEY_CTX_set_rsa_pss_saltlen| for details of the special values that it +// `EVP_PKEY_CTX_set_rsa_pss_saltlen` for details of the special values that it // can take. // // Returns one on success or zero on error. @@ -1066,14 +1066,14 @@ OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int bits); -// EVP_PKEY_CTX_set_rsa_keygen_pubexp sets |e| as the public exponent for key -// generation. Returns one on success or zero on error. On success, |ctx| takes -// ownership of |e|. The library will then call |BN_free| on |e| when |ctx| is +// EVP_PKEY_CTX_set_rsa_keygen_pubexp sets `e` as the public exponent for key +// generation. Returns one on success or zero on error. On success, `ctx` takes +// ownership of `e`. The library will then call `BN_free` on `e` when `ctx` is // destroyed. OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *e); -// EVP_PKEY_CTX_set_rsa_oaep_md sets |md| as the digest used in OAEP padding. +// EVP_PKEY_CTX_set_rsa_oaep_md sets `md` as the digest used in OAEP padding. // Returns one on success or zero on error. If unset, the default is SHA-1. // Callers are recommended to overwrite this default. // @@ -1081,35 +1081,35 @@ OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); -// EVP_PKEY_CTX_get_rsa_oaep_md sets |*out_md| to the digest function used in +// EVP_PKEY_CTX_get_rsa_oaep_md sets `*out_md` to the digest function used in // OAEP padding. Returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **out_md); -// EVP_PKEY_CTX_set_rsa_mgf1_md sets |md| as the digest used in MGF1. Returns +// EVP_PKEY_CTX_set_rsa_mgf1_md sets `md` as the digest used in MGF1. Returns // one on success or zero on error. // -// If unset, the default is the signing hash for |RSA_PKCS1_PSS_PADDING| and the -// OAEP hash for |RSA_PKCS1_OAEP_PADDING|. Callers are recommended to use this +// If unset, the default is the signing hash for `RSA_PKCS1_PSS_PADDING` and the +// OAEP hash for `RSA_PKCS1_OAEP_PADDING`. Callers are recommended to use this // default and not call this function. OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); -// EVP_PKEY_CTX_get_rsa_mgf1_md sets |*out_md| to the digest function used in +// EVP_PKEY_CTX_get_rsa_mgf1_md sets `*out_md` to the digest function used in // MGF1. Returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **out_md); -// EVP_PKEY_CTX_set0_rsa_oaep_label sets |label_len| bytes from |label| as the -// label used in OAEP. DANGER: On success, this call takes ownership of |label| -// and will call |OPENSSL_free| on it when |ctx| is destroyed. +// EVP_PKEY_CTX_set0_rsa_oaep_label sets `label_len` bytes from `label` as the +// label used in OAEP. DANGER: On success, this call takes ownership of `label` +// and will call `OPENSSL_free` on it when `ctx` is destroyed. // // Returns one on success or zero on error. OPENSSL_EXPORT int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, uint8_t *label, size_t label_len); -// EVP_PKEY_CTX_get0_rsa_oaep_label sets |*out_label| to point to the internal +// EVP_PKEY_CTX_get0_rsa_oaep_label sets `*out_label` to point to the internal // buffer containing the OAEP label (which may be NULL) and returns the length // of the label or a negative value on error. // @@ -1120,16 +1120,16 @@ // EC specific control functions. -// EVP_PKEY_get_ec_curve_nid returns |pkey|'s curve as a NID constant, such as -// |NID_X9_62_prime256v1|, or |NID_undef| if |pkey| is not an EC key. +// EVP_PKEY_get_ec_curve_nid returns `pkey`'s curve as a NID constant, such as +// `NID_X9_62_prime256v1`, or `NID_undef` if `pkey` is not an EC key. OPENSSL_EXPORT int EVP_PKEY_get_ec_curve_nid(const EVP_PKEY *pkey); -// EVP_PKEY_get_ec_point_conv_form returns |pkey|'s point conversion form as a -// |POINT_CONVERSION_*| constant, or zero if |pkey| is not an EC key. +// EVP_PKEY_get_ec_point_conv_form returns `pkey`'s point conversion form as a +// `POINT_CONVERSION_*` constant, or zero if `pkey` is not an EC key. OPENSSL_EXPORT int EVP_PKEY_get_ec_point_conv_form(const EVP_PKEY *pkey); // EVP_PKEY_CTX_set_ec_paramgen_curve_nid sets the curve used for -// |EVP_PKEY_keygen| or |EVP_PKEY_paramgen| operations to |nid|. It returns one +// `EVP_PKEY_keygen` or `EVP_PKEY_paramgen` operations to `nid`. It returns one // on success and zero on error. OPENSSL_EXPORT int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); @@ -1137,14 +1137,14 @@ // Diffie-Hellman-specific control functions. -// EVP_PKEY_CTX_set_dh_pad configures configures whether |ctx|, which must be an -// |EVP_PKEY_derive| operation, configures the handling of leading zeros in the -// Diffie-Hellman shared secret. If |pad| is zero, leading zeros are removed -// from the secret. If |pad| is non-zero, the fixed-width shared secret is used +// EVP_PKEY_CTX_set_dh_pad configures configures whether `ctx`, which must be an +// `EVP_PKEY_derive` operation, configures the handling of leading zeros in the +// Diffie-Hellman shared secret. If `pad` is zero, leading zeros are removed +// from the secret. If `pad` is non-zero, the fixed-width shared secret is used // unmodified, as in PKCS #3. If this function is not called, the default is to // remove leading zeros. // -// WARNING: The behavior when |pad| is zero leaks information about the shared +// WARNING: The behavior when `pad` is zero leaks information about the shared // secret. This may result in side channel attacks such as // https://raccoon-attack.com/, particularly when the same private key is used // for multiple operations. @@ -1156,15 +1156,15 @@ // Two APIs for working with key encapsulation mechanism (KEM) algorithms are // provided: // -// 1. Create an |EVP_PKEY_CTX|, initialize it for the appropriate KEM operation -// (see |EVP_PKEY_encapsulate_init| and |EVP_PKEY_decapsulate_init|), then +// 1. Create an `EVP_PKEY_CTX`, initialize it for the appropriate KEM operation +// (see `EVP_PKEY_encapsulate_init` and `EVP_PKEY_decapsulate_init`), then // run the operation. This matches the OpenSSL API. // -// 2. Pass an appropriate |EVP_KEM| object to the functions below to use it -// for encapsulation and decapsulation operations with compatible |EVP_PKEY| +// 2. Pass an appropriate `EVP_KEM` object to the functions below to use it +// for encapsulation and decapsulation operations with compatible `EVP_PKEY` // objects. This API requires fewer steps. // -// The |EVP_KEM| API is only compatible with KEMs that use fixed-length +// The `EVP_KEM` API is only compatible with KEMs that use fixed-length // ciphertexts and secrets. // EVP_kem_ml_kem_* implement ML-KEM, defined in FIPS 203. @@ -1178,32 +1178,32 @@ // TODO(crbug.com/449751916): Add more supported KEMs. // EVP_KEM_ciphertext_len returns the fixed length, in bytes, of a ciphertext -// produced and consumed by |kem|. +// produced and consumed by `kem`. OPENSSL_EXPORT size_t EVP_KEM_ciphertext_len(const EVP_KEM *kem); // EVP_KEM_secret_len returns the fixed length, in bytes, of the shared -// secret produced and consumed by |kem|. +// secret produced and consumed by `kem`. OPENSSL_EXPORT size_t EVP_KEM_secret_len(const EVP_KEM *kem); -// EVP_KEM_encap uses |kem| to encapsulate a |peer_key|. It outputs a -// ciphertext of length |ciphertext_len| into |*out_ciphertext| and outputs a -// shared secret of length |secret_len| into |*out_secret|. |peer_key| must be -// a public key of the type expected by |kem|. |ciphertext_len| and -// |secret_len| must match the output of |EVP_KEM_ciphertext_len| and -// |EVP_KEM_secret_len|, respectively, when called with |kem|. This function +// EVP_KEM_encap uses `kem` to encapsulate a `peer_key`. It outputs a +// ciphertext of length `ciphertext_len` into `*out_ciphertext` and outputs a +// shared secret of length `secret_len` into `*out_secret`. `peer_key` must be +// a public key of the type expected by `kem`. `ciphertext_len` and +// `secret_len` must match the output of `EVP_KEM_ciphertext_len` and +// `EVP_KEM_secret_len`, respectively, when called with `kem`. This function // returns one on success or zero on failure. OPENSSL_EXPORT int EVP_KEM_encap(const EVP_KEM *kem, uint8_t *out_ciphertext, size_t ciphertext_len, uint8_t *out_secret, size_t secret_len, const EVP_PKEY *peer_key); -// EVP_KEM_decap uses |kem| to decapsulate a |ciphertext| of length -// |ciphertext_len|, using |key| as a decapsulation key. It outputs a shared -// secret of length |secret_len| into |*out_secret|. |key| must be a private key -// of the type expected by |kem|. |secret_len| must match the output of -// |EVP_KEM_secret_len| when called with |kem|. This function returns one on -// success or zero on failure. If |ciphertext| has been corrupted, the function +// EVP_KEM_decap uses `kem` to decapsulate a `ciphertext` of length +// `ciphertext_len`, using `key` as a decapsulation key. It outputs a shared +// secret of length `secret_len` into `*out_secret`. `key` must be a private key +// of the type expected by `kem`. `secret_len` must match the output of +// `EVP_KEM_secret_len` when called with `kem`. This function returns one on +// success or zero on failure. If `ciphertext` has been corrupted, the function // may fail or it may output a shared secret that appears to be random. Any -// subsequent symmetric encryption using |*out_secret| must use an authenticated +// subsequent symmetric encryption using `*out_secret` must use an authenticated // encryption scheme in order to discover the decapsulation failure. OPENSSL_EXPORT int EVP_KEM_decap(const EVP_KEM *kem, uint8_t *out_secret, size_t secret_len, const uint8_t *ciphertext, @@ -1225,7 +1225,7 @@ #define EVP_PKEY_ED448 NID_ED448 // EVP_PKEY_get0 returns NULL. This function is provided for compatibility with -// OpenSSL but does not return anything. Use the typed |EVP_PKEY_get0_*| +// OpenSSL but does not return anything. Use the typed `EVP_PKEY_get0_*` // functions instead. OPENSSL_EXPORT void *EVP_PKEY_get0(const EVP_PKEY *pkey); @@ -1244,7 +1244,7 @@ // EVP_cleanup does nothing. OPENSSL_EXPORT void EVP_cleanup(void); -// EVP_default_properties_is_fips_enabled calls |FIPS_mode|. +// EVP_default_properties_is_fips_enabled calls `FIPS_mode`. OPENSSL_EXPORT int EVP_default_properties_is_fips_enabled(OSSL_LIB_CTX *libctx); OPENSSL_EXPORT void EVP_CIPHER_do_all_sorted( @@ -1267,82 +1267,82 @@ OPENSSL_EXPORT void EVP_MD_do_all_provided( OSSL_LIB_CTX *libctx, void (*callback)(EVP_MD *md, void *arg), void *arg); -// i2d_PrivateKey marshals a private key from |key| to type-specific format, as -// described in |i2d_SAMPLE|. +// i2d_PrivateKey marshals a private key from `key` to type-specific format, as +// described in `i2d_SAMPLE`. // // RSA keys are serialized as a DER-encoded RSAPublicKey (RFC 8017) structure. // EC keys are serialized as a DER-encoded ECPrivateKey (RFC 5915) structure. // -// Use |RSA_marshal_private_key| or |EC_KEY_marshal_private_key| instead. +// Use `RSA_marshal_private_key` or `EC_KEY_marshal_private_key` instead. OPENSSL_EXPORT int i2d_PrivateKey(const EVP_PKEY *key, uint8_t **outp); -// i2d_PublicKey marshals a public key from |key| to a type-specific format, as -// described in |i2d_SAMPLE|. +// i2d_PublicKey marshals a public key from `key` to a type-specific format, as +// described in `i2d_SAMPLE`. // // RSA keys are serialized as a DER-encoded RSAPublicKey (RFC 8017) structure. // EC keys are serialized as an EC point per SEC 1. // -// Use |RSA_marshal_public_key| or |EC_POINT_point2cbb| instead. +// Use `RSA_marshal_public_key` or `EC_POINT_point2cbb` instead. OPENSSL_EXPORT int i2d_PublicKey(const EVP_PKEY *key, uint8_t **outp); -// d2i_PrivateKey parses a DER-encoded private key from |len| bytes at |*inp|, -// as described in |d2i_SAMPLE|. The private key must have type |type|, +// d2i_PrivateKey parses a DER-encoded private key from `len` bytes at `*inp`, +// as described in `d2i_SAMPLE`. The private key must have type `type`, // otherwise it will be rejected. // // This function tries to detect one of several formats. Instead, use -// |EVP_parse_private_key| for a PrivateKeyInfo, |RSA_parse_private_key| for an -// RSAPrivateKey, and |EC_parse_private_key| for an ECPrivateKey. +// `EVP_parse_private_key` for a PrivateKeyInfo, `RSA_parse_private_key` for an +// RSAPrivateKey, and `EC_parse_private_key` for an ECPrivateKey. OPENSSL_EXPORT EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **out, const uint8_t **inp, long len); -// d2i_AutoPrivateKey acts the same as |d2i_PrivateKey|, but detects the type +// d2i_AutoPrivateKey acts the same as `d2i_PrivateKey`, but detects the type // of the private key. // // This function tries to detect one of several formats. Instead, use -// |EVP_parse_private_key| for a PrivateKeyInfo, |RSA_parse_private_key| for an -// RSAPrivateKey, and |EC_parse_private_key| for an ECPrivateKey. +// `EVP_parse_private_key` for a PrivateKeyInfo, `RSA_parse_private_key` for an +// RSAPrivateKey, and `EC_parse_private_key` for an ECPrivateKey. OPENSSL_EXPORT EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **out, const uint8_t **inp, long len); -// d2i_PublicKey parses a public key from |len| bytes at |*inp| in a type- -// specific format specified by |type|, as described in |d2i_SAMPLE|. +// d2i_PublicKey parses a public key from `len` bytes at `*inp` in a type- +// specific format specified by `type`, as described in `d2i_SAMPLE`. // -// The only supported value for |type| is |EVP_PKEY_RSA|, which parses a +// The only supported value for `type` is `EVP_PKEY_RSA`, which parses a // DER-encoded RSAPublicKey (RFC 8017) structure. Parsing EC keys is not // supported by this function. // -// Use |RSA_parse_public_key| instead. +// Use `RSA_parse_public_key` instead. OPENSSL_EXPORT EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **out, const uint8_t **inp, long len); -// EVP_PKEY_CTX_set_ec_param_enc returns one if |encoding| is -// |OPENSSL_EC_NAMED_CURVE| or zero with an error otherwise. +// EVP_PKEY_CTX_set_ec_param_enc returns one if `encoding` is +// `OPENSSL_EC_NAMED_CURVE` or zero with an error otherwise. OPENSSL_EXPORT int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int encoding); -// EVP_PKEY_set_type sets the type of |pkey| to |type|. It returns one if -// successful or zero if the |type| argument is not one of the |EVP_PKEY_*| -// values supported for use with this function. If |pkey| is NULL, it simply +// EVP_PKEY_set_type sets the type of `pkey` to `type`. It returns one if +// successful or zero if the `type` argument is not one of the `EVP_PKEY_*` +// values supported for use with this function. If `pkey` is NULL, it simply // reports whether the type is known. // -// There are very few cases where this function is useful. Changing |pkey|'s +// There are very few cases where this function is useful. Changing `pkey`'s // type clears any previously stored keys, so there is no benefit to loading a -// key and then changing its type. Although |pkey| is left with a type +// key and then changing its type. Although `pkey` is left with a type // configured, it has no key, and functions which set a key, such as -// |EVP_PKEY_set1_RSA|, will configure a type anyway. If writing unit tests that +// `EVP_PKEY_set1_RSA`, will configure a type anyway. If writing unit tests that // are only sensitive to the type of a key, it is preferable to construct a real // key, so that tests are more representative of production code. // // The only API pattern which requires this function is -// |EVP_PKEY_set1_tls_encodedpoint| with X25519, which requires a half-empty -// |EVP_PKEY| that was first configured with |EVP_PKEY_X25519|. Currently, all -// other values of |type| will result in an error. +// `EVP_PKEY_set1_tls_encodedpoint` with X25519, which requires a half-empty +// `EVP_PKEY` that was first configured with `EVP_PKEY_X25519`. Currently, all +// other values of `type` will result in an error. OPENSSL_EXPORT int EVP_PKEY_set_type(EVP_PKEY *pkey, int type); -// EVP_PKEY_set1_tls_encodedpoint replaces |pkey| with a public key encoded by -// |in|. It returns one on success and zero on error. +// EVP_PKEY_set1_tls_encodedpoint replaces `pkey` with a public key encoded by +// `in`. It returns one on success and zero on error. // -// If |pkey| is an EC key, the format is an X9.62 point and |pkey| must already +// If `pkey` is an EC key, the format is an X9.62 point and `pkey` must already // have an EC group configured. If it is an X25519 key, it is the 32-byte X25519 // public key representation. This function is not supported for other key types // and will fail. @@ -1350,19 +1350,19 @@ const uint8_t *in, size_t len); -// EVP_PKEY_get1_tls_encodedpoint sets |*out_ptr| to a newly-allocated buffer -// containing the raw encoded public key for |pkey|. The caller must call -// |OPENSSL_free| to release this buffer. The function returns the length of the +// EVP_PKEY_get1_tls_encodedpoint sets `*out_ptr` to a newly-allocated buffer +// containing the raw encoded public key for `pkey`. The caller must call +// `OPENSSL_free` to release this buffer. The function returns the length of the // buffer on success and zero on error. // -// If |pkey| is an EC key, the format is an X9.62 point with uncompressed +// If `pkey` is an EC key, the format is an X9.62 point with uncompressed // coordinates. If it is an X25519 key, it is the 32-byte X25519 public key // representation. This function is not supported for other key types and will // fail. OPENSSL_EXPORT size_t EVP_PKEY_get1_tls_encodedpoint(const EVP_PKEY *pkey, uint8_t **out_ptr); -// EVP_PKEY_base_id calls |EVP_PKEY_id|. +// EVP_PKEY_base_id calls `EVP_PKEY_id`. OPENSSL_EXPORT int EVP_PKEY_base_id(const EVP_PKEY *pkey); // EVP_PKEY_CTX_set_rsa_pss_keygen_md returns 0. @@ -1377,56 +1377,56 @@ OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); -// i2d_PUBKEY marshals |pkey| as a DER-encoded SubjectPublicKeyInfo, as -// described in |i2d_SAMPLE|. +// i2d_PUBKEY marshals `pkey` as a DER-encoded SubjectPublicKeyInfo, as +// described in `i2d_SAMPLE`. // -// Use |EVP_marshal_public_key| instead. +// Use `EVP_marshal_public_key` instead. OPENSSL_EXPORT int i2d_PUBKEY(const EVP_PKEY *pkey, uint8_t **outp); -// d2i_PUBKEY parses a DER-encoded SubjectPublicKeyInfo from |len| bytes at -// |*inp|, as described in |d2i_SAMPLE|. +// d2i_PUBKEY parses a DER-encoded SubjectPublicKeyInfo from `len` bytes at +// `*inp`, as described in `d2i_SAMPLE`. // -// Use |EVP_parse_public_key| instead. +// Use `EVP_parse_public_key` instead. OPENSSL_EXPORT EVP_PKEY *d2i_PUBKEY(EVP_PKEY **out, const uint8_t **inp, long len); -// i2d_RSA_PUBKEY marshals |rsa| as a DER-encoded SubjectPublicKeyInfo -// structure, as described in |i2d_SAMPLE|. +// i2d_RSA_PUBKEY marshals `rsa` as a DER-encoded SubjectPublicKeyInfo +// structure, as described in `i2d_SAMPLE`. // -// Use |EVP_marshal_public_key| instead. +// Use `EVP_marshal_public_key` instead. OPENSSL_EXPORT int i2d_RSA_PUBKEY(const RSA *rsa, uint8_t **outp); // d2i_RSA_PUBKEY parses an RSA public key as a DER-encoded SubjectPublicKeyInfo -// from |len| bytes at |*inp|, as described in |d2i_SAMPLE|. +// from `len` bytes at `*inp`, as described in `d2i_SAMPLE`. // SubjectPublicKeyInfo structures containing other key types are rejected. // -// Use |EVP_parse_public_key| instead. +// Use `EVP_parse_public_key` instead. OPENSSL_EXPORT RSA *d2i_RSA_PUBKEY(RSA **out, const uint8_t **inp, long len); -// i2d_DSA_PUBKEY marshals |dsa| as a DER-encoded SubjectPublicKeyInfo, as -// described in |i2d_SAMPLE|. +// i2d_DSA_PUBKEY marshals `dsa` as a DER-encoded SubjectPublicKeyInfo, as +// described in `i2d_SAMPLE`. // -// Use |EVP_marshal_public_key| instead. +// Use `EVP_marshal_public_key` instead. OPENSSL_EXPORT int i2d_DSA_PUBKEY(const DSA *dsa, uint8_t **outp); // d2i_DSA_PUBKEY parses a DSA public key as a DER-encoded SubjectPublicKeyInfo -// from |len| bytes at |*inp|, as described in |d2i_SAMPLE|. +// from `len` bytes at `*inp`, as described in `d2i_SAMPLE`. // SubjectPublicKeyInfo structures containing other key types are rejected. // -// Use |EVP_parse_public_key| instead. +// Use `EVP_parse_public_key` instead. OPENSSL_EXPORT DSA *d2i_DSA_PUBKEY(DSA **out, const uint8_t **inp, long len); -// i2d_EC_PUBKEY marshals |ec_key| as a DER-encoded SubjectPublicKeyInfo, as -// described in |i2d_SAMPLE|. +// i2d_EC_PUBKEY marshals `ec_key` as a DER-encoded SubjectPublicKeyInfo, as +// described in `i2d_SAMPLE`. // -// Use |EVP_marshal_public_key| instead. +// Use `EVP_marshal_public_key` instead. OPENSSL_EXPORT int i2d_EC_PUBKEY(const EC_KEY *ec_key, uint8_t **outp); // d2i_EC_PUBKEY parses an EC public key as a DER-encoded SubjectPublicKeyInfo -// from |len| bytes at |*inp|, as described in |d2i_SAMPLE|. +// from `len` bytes at `*inp`, as described in `d2i_SAMPLE`. // SubjectPublicKeyInfo structures containing other key types are rejected. // -// Use |EVP_parse_public_key| instead. +// Use `EVP_parse_public_key` instead. OPENSSL_EXPORT EC_KEY *d2i_EC_PUBKEY(EC_KEY **out, const uint8_t **inp, long len); @@ -1438,45 +1438,45 @@ OPENSSL_EXPORT int EVP_PKEY_CTX_set_dsa_paramgen_q_bits(EVP_PKEY_CTX *ctx, int qbits); -// EVP_PKEY_assign sets the underlying key of |pkey| to |key|, which must be of -// the given type. If successful, it returns one. If the |type| argument -// is not one of |EVP_PKEY_RSA|, |EVP_PKEY_DSA|, or |EVP_PKEY_EC| values or if -// |key| is NULL, it returns zero. This function may not be used with other -// |EVP_PKEY_*| types. +// EVP_PKEY_assign sets the underlying key of `pkey` to `key`, which must be of +// the given type. If successful, it returns one. If the `type` argument +// is not one of `EVP_PKEY_RSA`, `EVP_PKEY_DSA`, or `EVP_PKEY_EC` values or if +// `key` is NULL, it returns zero. This function may not be used with other +// `EVP_PKEY_*` types. // -// Use the |EVP_PKEY_assign_*| functions instead. +// Use the `EVP_PKEY_assign_*` functions instead. OPENSSL_EXPORT int EVP_PKEY_assign(EVP_PKEY *pkey, int type, void *key); -// EVP_PKEY_type returns |nid|. +// EVP_PKEY_type returns `nid`. OPENSSL_EXPORT int EVP_PKEY_type(int nid); -// EVP_PKEY_new_raw_private_key interprets |in| as a raw private key of type -// |type|, which must be an |EVP_PKEY_*| constant, such as |EVP_PKEY_X25519|, -// and returns a newly-allocated |EVP_PKEY|, or nullptr on error. +// EVP_PKEY_new_raw_private_key interprets `in` as a raw private key of type +// `type`, which must be an `EVP_PKEY_*` constant, such as `EVP_PKEY_X25519`, +// and returns a newly-allocated `EVP_PKEY`, or nullptr on error. // -// Prefer |EVP_PKEY_from_raw_private_key|, which allows dead code elimination to +// Prefer `EVP_PKEY_from_raw_private_key`, which allows dead code elimination to // discard algorithms that aren't reachable from the caller. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *unused, const uint8_t *in, size_t len); -// EVP_PKEY_new_raw_public_key interprets |in| as a raw public key of type -// |type|, which must be an |EVP_PKEY_*| constant, such as |EVP_PKEY_X25519|, -// and returns a newly-allocated |EVP_PKEY|, or nullptr on error. +// EVP_PKEY_new_raw_public_key interprets `in` as a raw public key of type +// `type`, which must be an `EVP_PKEY_*` constant, such as `EVP_PKEY_X25519`, +// and returns a newly-allocated `EVP_PKEY`, or nullptr on error. // -// Prefer |EVP_PKEY_from_raw_private_key|, which allows dead code elimination to +// Prefer `EVP_PKEY_from_raw_private_key`, which allows dead code elimination to // discard algorithms that aren't reachable from the caller. OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *unused, const uint8_t *in, size_t len); -// EVP_PKEY_cmp calls |EVP_PKEY_eq|. It returns one if public keys are equal and +// EVP_PKEY_cmp calls `EVP_PKEY_eq`. It returns one if public keys are equal and // zero otherwise. // // WARNING: This differs from the traditional return value of a "cmp" function. OPENSSL_EXPORT int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); -// EVP_PKEY_cmp_parameters calls |EVP_PKEY_parameters_eq|. It returns one if +// EVP_PKEY_cmp_parameters calls `EVP_PKEY_parameters_eq`. It returns one if // parameters are equal and zero otherwise. // // WARNING: This differs from the traditional return value of a "cmp" function. @@ -1490,7 +1490,7 @@ // constants to 'ctrl' functions. To avoid breaking #ifdefs in consumers, this // section defines a number of legacy macros. -// |BORINGSSL_PREFIX| already makes some of these symbols into macros, so there +// `BORINGSSL_PREFIX` already makes some of these symbols into macros, so there // is no need to define conflicting macros; however it is compiler specific // which ones become macros. #if !defined(EVP_PKEY_CTX_set_rsa_oaep_md)
diff --git a/include/openssl/ex_data.h b/include/openssl/ex_data.h index 6bb1874..1e567fe 100644 --- a/include/openssl/ex_data.h +++ b/include/openssl/ex_data.h
@@ -35,9 +35,9 @@ // Each type that supports ex_data provides three functions: -// TYPE_get_ex_new_index allocates a new index for |TYPE|. An optional -// |free_func| argument may be provided which is called when the owning object -// is destroyed. See |CRYPTO_EX_free| for details. The |argl| and |argp| +// TYPE_get_ex_new_index allocates a new index for `TYPE`. An optional +// `free_func` argument may be provided which is called when the owning object +// is destroyed. See `CRYPTO_EX_free` for details. The `argl` and `argp` // arguments are opaque values that are passed to the callback. It returns the // new index or a negative number on error. OPENSSL_EXPORT int TYPE_get_ex_new_index(long argl, void *argp, @@ -45,24 +45,24 @@ CRYPTO_EX_dup *dup_unused, CRYPTO_EX_free *free_func); -// TYPE_set_ex_data sets an extra data pointer on |t|. The |index| argument -// must have been returned from a previous call to |TYPE_get_ex_new_index|. +// TYPE_set_ex_data sets an extra data pointer on `t`. The `index` argument +// must have been returned from a previous call to `TYPE_get_ex_new_index`. OPENSSL_EXPORT int TYPE_set_ex_data(TYPE *t, int index, void *arg); -// TYPE_get_ex_data returns an extra data pointer for |t|, or NULL if no such -// pointer exists. The |index| argument should have been returned from a -// previous call to |TYPE_get_ex_new_index|. +// TYPE_get_ex_data returns an extra data pointer for `t`, or NULL if no such +// pointer exists. The `index` argument should have been returned from a +// previous call to `TYPE_get_ex_new_index`. OPENSSL_EXPORT void *TYPE_get_ex_data(const TYPE *t, int index); // Some types additionally preallocate index zero, with all callbacks set to // NULL. Applications that do not need the general ex_data machinery may use // this instead. -// TYPE_set_app_data sets |t|'s application data pointer to |arg|. It returns +// TYPE_set_app_data sets `t`'s application data pointer to `arg`. It returns // one on success and zero on error. OPENSSL_EXPORT int TYPE_set_app_data(TYPE *t, void *arg); -// TYPE_get_app_data returns the application data pointer for |t|, or NULL if no +// TYPE_get_app_data returns the application data pointer for `t`, or NULL if no // such pointer exists. OPENSSL_EXPORT void *TYPE_get_app_data(const TYPE *t); @@ -77,19 +77,19 @@ // CRYPTO_EX_free is a callback function that is called when an object of the // class with extra data pointers is being destroyed. For example, if this -// callback has been passed to |SSL_get_ex_new_index| then it may be called each -// time an |SSL*| is destroyed. +// callback has been passed to `SSL_get_ex_new_index` then it may be called each +// time an `SSL*` is destroyed. // -// |parent| and |ad| will be NULL. Historically, the parent object was passed in -// |parent|, but accessing the pointer was not safe because |parent| was in the +// `parent` and `ad` will be NULL. Historically, the parent object was passed in +// `parent`, but accessing the pointer was not safe because `parent` was in the // process of being destroyed. If the callback has access to some other pointer // to the parent object, it must not pass the pointer to any BoringSSL APIs. // Mid-destruction, invariants on the parent object no longer hold. // -// The arguments |argl| and |argp| contain opaque values that were given to -// |CRYPTO_get_ex_new_index_ex|. +// The arguments `argl` and `argp` contain opaque values that were given to +// `CRYPTO_get_ex_new_index_ex`. // -// This callback may be called with a NULL value for |ptr| if the object has no +// This callback may be called with a NULL value for `ptr` if the object has no // value set for this index. However, the callbacks may also be skipped entirely // if no extra data pointers are set on the object at all. typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
diff --git a/ssl/extensions.cc b/ssl/extensions.cc index 3ce85b3..fb067c6 100644 --- a/ssl/extensions.cc +++ b/ssl/extensions.cc
@@ -726,9 +726,12 @@ static bool ext_ri_parse_serverhello(SSL_HANDSHAKE *hs, uint8_t *out_alert, CBS *contents) { SSL *const ssl = hs->ssl; - if (contents != nullptr && ssl_protocol_version(ssl) >= TLS1_3_VERSION) { - *out_alert = SSL_AD_ILLEGAL_PARAMETER; - return false; + if (ssl_protocol_version(ssl) >= TLS1_3_VERSION) { + if (contents != nullptr) { + *out_alert = SSL_AD_ILLEGAL_PARAMETER; + return false; + } + return true; } // Servers may not switch between omitting the extension and supporting it.
diff --git a/ssl/test/runner/renegotiation_tests.go b/ssl/test/runner/renegotiation_tests.go index f67bf4d..cceabc3 100644 --- a/ssl/test/runner/renegotiation_tests.go +++ b/ssl/test/runner/renegotiation_tests.go
@@ -190,6 +190,16 @@ expectedError: ":UNSAFE_LEGACY_RENEGOTIATION_DISABLED:", }) + // Missing extension is OK (and expected!) in TLS 1.3, even if the + // extension is otherwise enforced. TLS 1.3 has no renegotiation. + testCases = append(testCases, testCase{ + name: "NoLegacyServerConnect-TLS13", + config: Config{ + MaxVersion: VersionTLS13, + }, + flags: []string{"-no-legacy-server-connect"}, + }) + // Test that the server may switch ciphers on renegotiation without // problems. testCases = append(testCases, testCase{
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()