Documentation: Change |...| to `...` for code references in comments 2/N This CL includes the result of running util/update_comment_style.py over all public header files in include/openssl whose filenames begin with c-e, and fixing omissions manually if necessary. Bug: 42290410 Change-Id: I306fb029389ab99725deead22e77ad5e6a6a6964 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/96127 Reviewed-by: David Benjamin <davidben@google.com> Commit-Queue: Lily Chen <chlily@google.com>
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,