Documentation: Change |...| to `...` for code references in comments 4/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 s-z, except for ssl.h, and fixing omissions manually if necessary. Bug: 42290410 Change-Id: Id1eba48c218a61bf367640d7bfa59d7a6a6a6964 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/96147 Reviewed-by: David Benjamin <davidben@google.com> Commit-Queue: Lily Chen <chlily@google.com>
diff --git a/include/openssl/sha.h b/include/openssl/sha.h index ba17bfa..a09889f 100644 --- a/include/openssl/sha.h +++ b/include/openssl/sha.h
@@ -38,26 +38,26 @@ // SHA_DIGEST_LENGTH is the length of a SHA-1 digest. #define SHA_DIGEST_LENGTH 20 -// SHA1_Init initialises |sha| and returns one. +// SHA1_Init initialises `sha` and returns one. OPENSSL_EXPORT int SHA1_Init(SHA_CTX *sha); -// SHA1_Update adds |len| bytes from |data| to |sha| and returns one. +// SHA1_Update adds `len` bytes from `data` to `sha` and returns one. OPENSSL_EXPORT int SHA1_Update(SHA_CTX *sha, const void *data, size_t len); -// SHA1_Final adds the final padding to |sha| and writes the resulting digest to -// |out|, which must have at least |SHA_DIGEST_LENGTH| bytes of space. It +// SHA1_Final adds the final padding to `sha` and writes the resulting digest to +// `out`, which must have at least `SHA_DIGEST_LENGTH` bytes of space. It // returns one. OPENSSL_EXPORT int SHA1_Final(uint8_t out[SHA_DIGEST_LENGTH], SHA_CTX *sha); -// SHA1 writes the digest of |len| bytes from |data| to |out| and returns -// |out|. There must be at least |SHA_DIGEST_LENGTH| bytes of space in -// |out|. +// SHA1 writes the digest of `len` bytes from `data` to `out` and returns +// `out`. There must be at least `SHA_DIGEST_LENGTH` bytes of space in +// `out`. OPENSSL_EXPORT uint8_t *SHA1(const uint8_t *data, size_t len, uint8_t out[SHA_DIGEST_LENGTH]); // SHA1_Transform is a low-level function that performs a single, SHA-1 block -// transformation using the state from |sha| and |SHA_CBLOCK| bytes from -// |block|. +// transformation using the state from `sha` and `SHA_CBLOCK` bytes from +// `block`. OPENSSL_EXPORT void SHA1_Transform(SHA_CTX *sha, const uint8_t block[SHA_CBLOCK]); @@ -65,7 +65,7 @@ #if defined(__cplusplus) || defined(OPENSSL_WINDOWS) uint32_t h[5]; #else - // wpa_supplicant accesses |h0|..|h4| so we must support those names for + // wpa_supplicant accesses `h0`..`h4` so we must support those names for // compatibility with it until it can be updated. Anonymous unions are only // standard in C11, so disable this workaround in C++. union { @@ -84,14 +84,14 @@ unsigned num; } /* SHA_CTX */; -// CRYPTO_fips_186_2_prf derives |out_len| bytes from |xkey| using the PRF +// CRYPTO_fips_186_2_prf derives `out_len` bytes from `xkey` using the PRF // defined in FIPS 186-2, Appendix 3.1, with change notice 1 applied. The b // parameter is 160 and seed, XKEY, is also 160 bits. The optional XSEED user // input is all zeros. // // The PRF generates a sequence of 320-bit numbers. Each number is encoded as a -// 40-byte string in big-endian and then concatenated to form |out|. If -// |out_len| is not a multiple of 40, the result is truncated. This matches the +// 40-byte string in big-endian and then concatenated to form `out`. If +// `out_len` is not a multiple of 40, the result is truncated. This matches the // construction used in Section 7 of RFC 4186 and Section 7 of RFC 4187. // // This PRF is based on SHA-1, a weak hash function, and should not be used
diff --git a/include/openssl/sha2.h b/include/openssl/sha2.h index 7bb3f21..349d280 100644 --- a/include/openssl/sha2.h +++ b/include/openssl/sha2.h
@@ -33,21 +33,21 @@ // SHA224_DIGEST_LENGTH is the length of a SHA-224 digest. #define SHA224_DIGEST_LENGTH 28 -// SHA224_Init initialises |sha| and returns 1. +// SHA224_Init initialises `sha` and returns 1. OPENSSL_EXPORT int SHA224_Init(SHA256_CTX *sha); -// SHA224_Update adds |len| bytes from |data| to |sha| and returns 1. +// SHA224_Update adds `len` bytes from `data` to `sha` and returns 1. OPENSSL_EXPORT int SHA224_Update(SHA256_CTX *sha, const void *data, size_t len); -// SHA224_Final adds the final padding to |sha| and writes the resulting digest -// to |out|, which must have at least |SHA224_DIGEST_LENGTH| bytes of space. It +// SHA224_Final adds the final padding to `sha` and writes the resulting digest +// to `out`, which must have at least `SHA224_DIGEST_LENGTH` bytes of space. It // returns 1. OPENSSL_EXPORT int SHA224_Final(uint8_t out[SHA224_DIGEST_LENGTH], SHA256_CTX *sha); -// SHA224 writes the digest of |len| bytes from |data| to |out| and returns -// |out|. There must be at least |SHA224_DIGEST_LENGTH| bytes of space in -// |out|. +// SHA224 writes the digest of `len` bytes from `data` to `out` and returns +// `out`. There must be at least `SHA224_DIGEST_LENGTH` bytes of space in +// `out`. OPENSSL_EXPORT uint8_t *SHA224(const uint8_t *data, size_t len, uint8_t out[SHA224_DIGEST_LENGTH]); @@ -60,33 +60,33 @@ // SHA256_DIGEST_LENGTH is the length of a SHA-256 digest. #define SHA256_DIGEST_LENGTH 32 -// SHA256_Init initialises |sha| and returns 1. +// SHA256_Init initialises `sha` and returns 1. OPENSSL_EXPORT int SHA256_Init(SHA256_CTX *sha); -// SHA256_Update adds |len| bytes from |data| to |sha| and returns 1. +// SHA256_Update adds `len` bytes from `data` to `sha` and returns 1. OPENSSL_EXPORT int SHA256_Update(SHA256_CTX *sha, const void *data, size_t len); -// SHA256_Final adds the final padding to |sha| and writes the resulting digest -// to |out|, which must have at least |SHA256_DIGEST_LENGTH| bytes of space. It +// SHA256_Final adds the final padding to `sha` and writes the resulting digest +// to `out`, which must have at least `SHA256_DIGEST_LENGTH` bytes of space. It // returns one on success and zero on programmer error. OPENSSL_EXPORT int SHA256_Final(uint8_t out[SHA256_DIGEST_LENGTH], SHA256_CTX *sha); -// SHA256 writes the digest of |len| bytes from |data| to |out| and returns -// |out|. There must be at least |SHA256_DIGEST_LENGTH| bytes of space in -// |out|. +// SHA256 writes the digest of `len` bytes from `data` to `out` and returns +// `out`. There must be at least `SHA256_DIGEST_LENGTH` bytes of space in +// `out`. OPENSSL_EXPORT uint8_t *SHA256(const uint8_t *data, size_t len, uint8_t out[SHA256_DIGEST_LENGTH]); // SHA256_Transform is a low-level function that performs a single, SHA-256 -// block transformation using the state from |sha| and |SHA256_CBLOCK| bytes -// from |block|. +// block transformation using the state from `sha` and `SHA256_CBLOCK` bytes +// from `block`. OPENSSL_EXPORT void SHA256_Transform(SHA256_CTX *sha, const uint8_t block[SHA256_CBLOCK]); -// SHA256_TransformBlocks is a low-level function that takes |num_blocks| * -// |SHA256_CBLOCK| bytes of data and performs SHA-256 transforms on it to update -// |state|. You should not use this function unless you are implementing a +// SHA256_TransformBlocks is a low-level function that takes `num_blocks` * +// `SHA256_CBLOCK` bytes of data and performs SHA-256 transforms on it to update +// `state`. You should not use this function unless you are implementing a // derivative of SHA-256. OPENSSL_EXPORT void SHA256_TransformBlocks(uint32_t state[8], const uint8_t *data, @@ -108,21 +108,21 @@ // SHA384_DIGEST_LENGTH is the length of a SHA-384 digest. #define SHA384_DIGEST_LENGTH 48 -// SHA384_Init initialises |sha| and returns 1. +// SHA384_Init initialises `sha` and returns 1. OPENSSL_EXPORT int SHA384_Init(SHA512_CTX *sha); -// SHA384_Update adds |len| bytes from |data| to |sha| and returns 1. +// SHA384_Update adds `len` bytes from `data` to `sha` and returns 1. OPENSSL_EXPORT int SHA384_Update(SHA512_CTX *sha, const void *data, size_t len); -// SHA384_Final adds the final padding to |sha| and writes the resulting digest -// to |out|, which must have at least |SHA384_DIGEST_LENGTH| bytes of space. It +// SHA384_Final adds the final padding to `sha` and writes the resulting digest +// to `out`, which must have at least `SHA384_DIGEST_LENGTH` bytes of space. It // returns one on success and zero on programmer error. OPENSSL_EXPORT int SHA384_Final(uint8_t out[SHA384_DIGEST_LENGTH], SHA512_CTX *sha); -// SHA384 writes the digest of |len| bytes from |data| to |out| and returns -// |out|. There must be at least |SHA384_DIGEST_LENGTH| bytes of space in -// |out|. +// SHA384 writes the digest of `len` bytes from `data` to `out` and returns +// `out`. There must be at least `SHA384_DIGEST_LENGTH` bytes of space in +// `out`. OPENSSL_EXPORT uint8_t *SHA384(const uint8_t *data, size_t len, uint8_t out[SHA384_DIGEST_LENGTH]); @@ -135,27 +135,27 @@ // SHA512_DIGEST_LENGTH is the length of a SHA-512 digest. #define SHA512_DIGEST_LENGTH 64 -// SHA512_Init initialises |sha| and returns 1. +// SHA512_Init initialises `sha` and returns 1. OPENSSL_EXPORT int SHA512_Init(SHA512_CTX *sha); -// SHA512_Update adds |len| bytes from |data| to |sha| and returns 1. +// SHA512_Update adds `len` bytes from `data` to `sha` and returns 1. OPENSSL_EXPORT int SHA512_Update(SHA512_CTX *sha, const void *data, size_t len); -// SHA512_Final adds the final padding to |sha| and writes the resulting digest -// to |out|, which must have at least |SHA512_DIGEST_LENGTH| bytes of space. It +// SHA512_Final adds the final padding to `sha` and writes the resulting digest +// to `out`, which must have at least `SHA512_DIGEST_LENGTH` bytes of space. It // returns one on success and zero on programmer error. OPENSSL_EXPORT int SHA512_Final(uint8_t out[SHA512_DIGEST_LENGTH], SHA512_CTX *sha); -// SHA512 writes the digest of |len| bytes from |data| to |out| and returns -// |out|. There must be at least |SHA512_DIGEST_LENGTH| bytes of space in -// |out|. +// SHA512 writes the digest of `len` bytes from `data` to `out` and returns +// `out`. There must be at least `SHA512_DIGEST_LENGTH` bytes of space in +// `out`. OPENSSL_EXPORT uint8_t *SHA512(const uint8_t *data, size_t len, uint8_t out[SHA512_DIGEST_LENGTH]); // SHA512_Transform is a low-level function that performs a single, SHA-512 -// block transformation using the state from |sha| and |SHA512_CBLOCK| bytes -// from |block|. +// block transformation using the state from `sha` and `SHA512_CBLOCK` bytes +// from `block`. OPENSSL_EXPORT void SHA512_Transform(SHA512_CTX *sha, const uint8_t block[SHA512_CBLOCK]); @@ -174,22 +174,22 @@ #define SHA512_256_DIGEST_LENGTH 32 -// SHA512_256_Init initialises |sha| and returns 1. +// SHA512_256_Init initialises `sha` and returns 1. OPENSSL_EXPORT int SHA512_256_Init(SHA512_CTX *sha); -// SHA512_256_Update adds |len| bytes from |data| to |sha| and returns 1. +// SHA512_256_Update adds `len` bytes from `data` to `sha` and returns 1. OPENSSL_EXPORT int SHA512_256_Update(SHA512_CTX *sha, const void *data, size_t len); -// SHA512_256_Final adds the final padding to |sha| and writes the resulting -// digest to |out|, which must have at least |SHA512_256_DIGEST_LENGTH| bytes of +// SHA512_256_Final adds the final padding to `sha` and writes the resulting +// digest to `out`, which must have at least `SHA512_256_DIGEST_LENGTH` bytes of // space. It returns one on success and zero on programmer error. OPENSSL_EXPORT int SHA512_256_Final(uint8_t out[SHA512_256_DIGEST_LENGTH], SHA512_CTX *sha); -// SHA512_256 writes the digest of |len| bytes from |data| to |out| and returns -// |out|. There must be at least |SHA512_256_DIGEST_LENGTH| bytes of space in -// |out|. +// SHA512_256 writes the digest of `len` bytes from `data` to `out` and returns +// `out`. There must be at least `SHA512_256_DIGEST_LENGTH` bytes of space in +// `out`. OPENSSL_EXPORT uint8_t *SHA512_256(const uint8_t *data, size_t len, uint8_t out[SHA512_256_DIGEST_LENGTH]);
diff --git a/include/openssl/slhdsa.h b/include/openssl/slhdsa.h index c9cda0c..9a535ba 100644 --- a/include/openssl/slhdsa.h +++ b/include/openssl/slhdsa.h
@@ -50,37 +50,37 @@ #define SLHDSA_SHAKE_256F_SIGNATURE_BYTES 49856 // SLHDSA_SHA2_128S_generate_key generates a SLH-DSA-SHA2-128s key pair and -// writes the result to |out_public_key| and |out_private_key|. +// writes the result to `out_public_key` and `out_private_key`. OPENSSL_EXPORT void SLHDSA_SHA2_128S_generate_key( uint8_t out_public_key[SLHDSA_SHA2_128S_PUBLIC_KEY_BYTES], uint8_t out_private_key[SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES]); // SLHDSA_SHAKE_256F_generate_key generates a SLH-DSA-SHAKE-256f key pair and -// writes the result to |out_public_key| and |out_private_key|. +// writes the result to `out_public_key` and `out_private_key`. OPENSSL_EXPORT void SLHDSA_SHAKE_256F_generate_key( uint8_t out_public_key[SLHDSA_SHAKE_256F_PUBLIC_KEY_BYTES], uint8_t out_private_key[SLHDSA_SHAKE_256F_PRIVATE_KEY_BYTES]); // SLHDSA_SHA2_128S_public_from_private writes the public key corresponding to -// |private_key| to |out_public_key|. +// `private_key` to `out_public_key`. OPENSSL_EXPORT void SLHDSA_SHA2_128S_public_from_private( uint8_t out_public_key[SLHDSA_SHA2_128S_PUBLIC_KEY_BYTES], const uint8_t private_key[SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES]); // SLHDSA_SHAKE_256F_public_from_private writes the public key corresponding to -// |private_key| to |out_public_key|. +// `private_key` to `out_public_key`. OPENSSL_EXPORT void SLHDSA_SHAKE_256F_public_from_private( uint8_t out_public_key[SLHDSA_SHAKE_256F_PUBLIC_KEY_BYTES], const uint8_t private_key[SLHDSA_SHAKE_256F_PRIVATE_KEY_BYTES]); -// SLHDSA_SHA2_128S_sign slowly generates a SLH-DSA-SHA2-128s signature of |msg| -// using |private_key| and writes it to |out_signature|. The |context| argument +// SLHDSA_SHA2_128S_sign slowly generates a SLH-DSA-SHA2-128s signature of `msg` +// using `private_key` and writes it to `out_signature`. The `context` argument // is also signed over and can be used to include implicit contextual -// information that isn't included in |msg|. The same value of |context| must be -// presented to |SLHDSA_SHA2_128S_verify| in order for the generated signature -// to be considered valid. |context| and |context_len| may be |NULL| and 0 to +// information that isn't included in `msg`. The same value of `context` must be +// presented to `SLHDSA_SHA2_128S_verify` in order for the generated signature +// to be considered valid. `context` and `context_len` may be `NULL` and 0 to // use an empty context (this is common). It returns 1 on success and 0 if -// |context_len| is larger than 255. +// `context_len` is larger than 255. OPENSSL_EXPORT int SLHDSA_SHA2_128S_sign( uint8_t out_signature[SLHDSA_SHA2_128S_SIGNATURE_BYTES], const uint8_t private_key[SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES], @@ -88,22 +88,22 @@ size_t context_len); // SLHDSA_SHAKE_256F_sign slowly generates a SLH-DSA-SHAKE-256f signature of -// |msg| using |private_key| and writes it to |out_signature|. The |context| +// `msg` using `private_key` and writes it to `out_signature`. The `context` // argument is also signed over and can be used to include implicit contextual -// information that isn't included in |msg|. The same value of |context| must be -// presented to |SLHDSA_SHAKE_256F_verify| in order for the generated signature -// to be considered valid. |context| and |context_len| may be |NULL| and 0 to +// information that isn't included in `msg`. The same value of `context` must be +// presented to `SLHDSA_SHAKE_256F_verify` in order for the generated signature +// to be considered valid. `context` and `context_len` may be `NULL` and 0 to // use an empty context (this is common). It returns 1 on success and 0 if -// |context_len| is larger than 255. +// `context_len` is larger than 255. OPENSSL_EXPORT int SLHDSA_SHAKE_256F_sign( uint8_t out_signature[SLHDSA_SHAKE_256F_SIGNATURE_BYTES], const uint8_t private_key[SLHDSA_SHAKE_256F_PRIVATE_KEY_BYTES], const uint8_t *msg, size_t msg_len, const uint8_t *context, size_t context_len); -// SLHDSA_SHA2_128S_verify verifies that |signature| is a valid -// SLH-DSA-SHA2-128s signature of |msg| by |public_key|. The value of |context| -// must equal the value that was passed to |SLHDSA_SHA2_128S_sign| when the +// SLHDSA_SHA2_128S_verify verifies that `signature` is a valid +// SLH-DSA-SHA2-128s signature of `msg` by `public_key`. The value of `context` +// must equal the value that was passed to `SLHDSA_SHA2_128S_sign` when the // signature was generated. It returns 1 if the signature is valid and 0 // otherwise. OPENSSL_EXPORT int SLHDSA_SHA2_128S_verify( @@ -112,9 +112,9 @@ const uint8_t *msg, size_t msg_len, const uint8_t *context, size_t context_len); -// SLHDSA_SHAKE_256F_verify verifies that |signature| is a valid -// SLH-DSA-SHAKE-256f signature of |msg| by |public_key|. The value of |context| -// must equal the value that was passed to |SLHDSA_SHAKE_256F_sign| when the +// SLHDSA_SHAKE_256F_verify verifies that `signature` is a valid +// SLH-DSA-SHAKE-256f signature of `msg` by `public_key`. The value of `context` +// must equal the value that was passed to `SLHDSA_SHAKE_256F_sign` when the // signature was generated. It returns 1 if the signature is valid and 0 // otherwise. OPENSSL_EXPORT int SLHDSA_SHAKE_256F_verify( @@ -137,20 +137,20 @@ // and there's no other way to prevent ambiguity. // SLHDSA_SHA2_128S_prehash_sign slowly generates a SLH-DSA-SHA2-128s signature -// of the prehashed |hashed_msg| using |private_key| and writes it to -// |out_signature|. The |context| argument is also signed over and can be used +// of the prehashed `hashed_msg` using `private_key` and writes it to +// `out_signature`. The `context` argument is also signed over and can be used // to include implicit contextual information that isn't included in -// |hashed_msg|. The same value of |context| must be presented to -// |SLHDSA_SHA2_128S_prehash_verify| in order for the generated signature to be -// considered valid. |context| and |context_len| may be |NULL| and 0 to use an +// `hashed_msg`. The same value of `context` must be presented to +// `SLHDSA_SHA2_128S_prehash_verify` in order for the generated signature to be +// considered valid. `context` and `context_len` may be `NULL` and 0 to use an // empty context (this is common). // -// The |hash_nid| argument must specify the hash function that was used to -// generate |hashed_msg|. This function only accepts hash functions listed in +// The `hash_nid` argument must specify the hash function that was used to +// generate `hashed_msg`. This function only accepts hash functions listed in // FIPS 205. // -// This function returns 1 on success and 0 if |context_len| is larger than 255, -// if the hash function is not supported, or if |hashed_msg| is the wrong +// This function returns 1 on success and 0 if `context_len` is larger than 255, +// if the hash function is not supported, or if `hashed_msg` is the wrong // length. OPENSSL_EXPORT int SLHDSA_SHA2_128S_prehash_sign( uint8_t out_signature[SLHDSA_SHA2_128S_SIGNATURE_BYTES], @@ -158,18 +158,18 @@ const uint8_t *hashed_msg, size_t hashed_msg_len, int hash_nid, const uint8_t *context, size_t context_len); -// SLHDSA_SHA2_128S_prehash_verify verifies that |signature| is a valid -// SLH-DSA-SHA2-128s signature of the prehashed |hashed_msg| by |public_key|, -// using the hash algorithm identified by |hash_nid|. The value of |context| -// must equal the value that was passed to |SLHDSA_SHA2_128S_prehash_sign| when +// SLHDSA_SHA2_128S_prehash_verify verifies that `signature` is a valid +// SLH-DSA-SHA2-128s signature of the prehashed `hashed_msg` by `public_key`, +// using the hash algorithm identified by `hash_nid`. The value of `context` +// must equal the value that was passed to `SLHDSA_SHA2_128S_prehash_sign` when // the signature was generated. // -// The |hash_nid| argument must specify the hash function that was used to -// generate |hashed_msg|. This function only accepts hash functions that are +// The `hash_nid` argument must specify the hash function that was used to +// generate `hashed_msg`. This function only accepts hash functions that are // listed in FIPS 205. // // This function returns 1 if the signature is valid and 0 if the signature is -// invalid, the hash function is not supported, or if |hashed_msg| is the wrong +// invalid, the hash function is not supported, or if `hashed_msg` is the wrong // length. OPENSSL_EXPORT int SLHDSA_SHA2_128S_prehash_verify( const uint8_t *signature, size_t signature_len, @@ -178,20 +178,20 @@ const uint8_t *context, size_t context_len); // SLHDSA_SHA2_128S_prehash_warning_nonstandard_sign slowly generates a -// SLH-DSA-SHA2-128s signature of the prehashed |hashed_msg| using |private_key| -// and writes it to |out_signature|. The |context| argument is also signed over +// SLH-DSA-SHA2-128s signature of the prehashed `hashed_msg` using `private_key` +// and writes it to `out_signature`. The `context` argument is also signed over // and can be used to include implicit contextual information that isn't -// included in |hashed_msg|. The same value of |context| must be presented to -// |SLHDSA_SHA2_128S_prehash_warning_nonstandard_verify| in order for the -// generated signature to be considered valid. |context| and |context_len| may -// be |NULL| and 0 to use an empty context (this is common). +// included in `hashed_msg`. The same value of `context` must be presented to +// `SLHDSA_SHA2_128S_prehash_warning_nonstandard_verify` in order for the +// generated signature to be considered valid. `context` and `context_len` may +// be `NULL` and 0 to use an empty context (this is common). // -// The |hash_nid| argument must specify the hash function that was used to -// generate |hashed_msg|. This function only accepts non-standard hash functions +// The `hash_nid` argument must specify the hash function that was used to +// generate `hashed_msg`. This function only accepts non-standard hash functions // that are not compliant with FIPS 205. // -// This function returns 1 on success and 0 if |context_len| is larger than 255, -// if the hash function is not supported, or if |hashed_msg| is the wrong +// This function returns 1 on success and 0 if `context_len` is larger than 255, +// if the hash function is not supported, or if `hashed_msg` is the wrong // length. OPENSSL_EXPORT int SLHDSA_SHA2_128S_prehash_warning_nonstandard_sign( uint8_t out_signature[SLHDSA_SHA2_128S_SIGNATURE_BYTES], @@ -199,18 +199,18 @@ const uint8_t *hashed_msg, size_t hashed_msg_len, int hash_nid, const uint8_t *context, size_t context_len); -// SLHDSA_SHA2_128S_prehash_warning_nonstandard_verify verifies that |signature| -// is a valid SLH-DSA-SHA2-128s signature of the prehashed |hashed_msg| by -// |public_key|, using the hash algorithm identified by |hash_nid|. The value of -// |context| must equal the value that was passed to -// |SLHDSA_SHA2_128S_prehash_sign| when the signature was generated. +// SLHDSA_SHA2_128S_prehash_warning_nonstandard_verify verifies that `signature` +// is a valid SLH-DSA-SHA2-128s signature of the prehashed `hashed_msg` by +// `public_key`, using the hash algorithm identified by `hash_nid`. The value of +// `context` must equal the value that was passed to +// `SLHDSA_SHA2_128S_prehash_sign` when the signature was generated. // -// The |hash_nid| argument must specify the hash function that was used to -// generate |hashed_msg|. This function only accepts non-standard hash functions +// The `hash_nid` argument must specify the hash function that was used to +// generate `hashed_msg`. This function only accepts non-standard hash functions // that are not compliant with FIPS 205. // // This function returns 1 if the signature is valid and 0 if the signature is -// invalid, the hash function is not supported, or if |hashed_msg| is the wrong +// invalid, the hash function is not supported, or if `hashed_msg` is the wrong // length. OPENSSL_EXPORT int SLHDSA_SHA2_128S_prehash_warning_nonstandard_verify( const uint8_t *signature, size_t signature_len,
diff --git a/include/openssl/span.h b/include/openssl/span.h index eb05f13..5f205b6 100644 --- a/include/openssl/span.h +++ b/include/openssl/span.h
@@ -113,12 +113,12 @@ } // namespace internal // A Span<T> is a non-owning reference to a contiguous array of objects of type -// |T|. Conceptually, a Span is a simple a pointer to |T| and a count of +// `T`. Conceptually, a Span is a simple a pointer to `T` and a count of // elements accessible via that pointer. The elements referenced by the Span can -// be mutated if |T| is mutable. +// be mutated if `T` is mutable. // -// A Span can be constructed from container types implementing |data()| and -// |size()| methods. If |T| is constant, construction from a container type is +// A Span can be constructed from container types implementing `data()` and +// `size()` methods. If `T` is constant, construction from a container type is // implicit. This allows writing methods that accept data from some unspecified // container type: // @@ -255,7 +255,7 @@ public: // NOTE: This method may abort() at runtime if pos or len are out of range. - // NOTE: As opposed to std::span, the |dynamic_extent| value of |len| is not + // NOTE: As opposed to std::span, the `dynamic_extent` value of `len` is not // magical here. This gets rid of a lot of runtime checks. constexpr Span<T> subspan(size_t pos, size_t len) const { // absl::Span throws an exception here. Note std::span and Chromium
diff --git a/include/openssl/ssl3.h b/include/openssl/ssl3.h index db04f98..d7d6481 100644 --- a/include/openssl/ssl3.h +++ b/include/openssl/ssl3.h
@@ -31,7 +31,7 @@ // The following constants are equal to TLS cipher suite values, OR-d with // 0x03000000. This is part of OpenSSL's SSL 2.0 legacy. SSL 2.0 has long since // been removed from BoringSSL. -// TODO(davidben): Define these in terms of |SSL_CIPHER_*| constants. The +// TODO(davidben): Define these in terms of `SSL_CIPHER_*` constants. The // challenge is that existing code expects them to be defined in ssl3.h, so we // must first merge ssl3.h into ssl.h. #define SSL3_CK_RSA_DES_192_CBC3_SHA 0x0300000A @@ -84,7 +84,7 @@ // bytes (256) plus the mac size. // // TODO(davidben): This derivation doesn't take AEADs into account, or TLS 1.1 -// explicit nonces. It happens to work because |SSL3_RT_MAX_MD_SIZE| is larger +// explicit nonces. It happens to work because `SSL3_RT_MAX_MD_SIZE` is larger // than necessary and no true AEAD has variable overhead in TLS 1.2. #define SSL3_RT_MAX_ENCRYPTED_OVERHEAD (256 + SSL3_RT_MAX_MD_SIZE) @@ -95,7 +95,7 @@ (EVP_AEAD_MAX_OVERHEAD + EVP_AEAD_MAX_NONCE_LENGTH) // SSL3_RT_MAX_COMPRESSED_LENGTH is an alias for -// |SSL3_RT_MAX_PLAIN_LENGTH|. Compression is gone, so don't include the +// `SSL3_RT_MAX_PLAIN_LENGTH`. Compression is gone, so don't include the // compression overhead. #define SSL3_RT_MAX_COMPRESSED_LENGTH SSL3_RT_MAX_PLAIN_LENGTH @@ -156,7 +156,7 @@ #define DTLS1_MT_HELLO_VERIFY_REQUEST 3 // The following are legacy aliases for consumers which use -// |SSL_CTX_set_msg_callback|. +// `SSL_CTX_set_msg_callback`. #define SSL3_MT_SERVER_DONE SSL3_MT_SERVER_HELLO_DONE #define SSL3_MT_NEWSESSION_TICKET SSL3_MT_NEW_SESSION_TICKET
diff --git a/include/openssl/stack.h b/include/openssl/stack.h index c88f6b3..18824d1 100644 --- a/include/openssl/stack.h +++ b/include/openssl/stack.h
@@ -26,56 +26,56 @@ // used collection object. // // This file defines macros for type-safe use of the stack functions. A stack -// type is named like |STACK_OF(FOO)| and is accessed with functions named -// like |sk_FOO_*|. Note the stack will typically contain /pointers/ to |FOO|. +// type is named like `STACK_OF(FOO)` and is accessed with functions named +// like `sk_FOO_*`. Note the stack will typically contain /pointers/ to `FOO`. // -// The |DECLARE_STACK_OF| macro makes |STACK_OF(FOO)| available, and -// |DEFINE_STACK_OF| makes the corresponding functions available. +// The `DECLARE_STACK_OF` macro makes `STACK_OF(FOO)` available, and +// `DEFINE_STACK_OF` makes the corresponding functions available. // Defining stacks. -// STACK_OF expands to the stack type for |type|. +// STACK_OF expands to the stack type for `type`. #define STACK_OF(type) struct stack_st_##type -// DECLARE_STACK_OF declares the |STACK_OF(type)| type. It does not make the -// corresponding |sk_type_*| functions available. This macro should be used in +// DECLARE_STACK_OF declares the `STACK_OF(type)` type. It does not make the +// corresponding `sk_type_*` functions available. This macro should be used in // files which only need the type. #define DECLARE_STACK_OF(type) STACK_OF(type); -// DEFINE_NAMED_STACK_OF defines |STACK_OF(name)| to be a stack whose elements -// are |type| *. This macro makes the |sk_name_*| functions available. +// DEFINE_NAMED_STACK_OF defines `STACK_OF(name)` to be a stack whose elements +// are `type` *. This macro makes the `sk_name_*` functions available. // -// It is not necessary to use |DECLARE_STACK_OF| in files which use this macro. +// It is not necessary to use `DECLARE_STACK_OF` in files which use this macro. // // Must be used from the global namespace. #define DEFINE_NAMED_STACK_OF(name, type) \ BORINGSSL_DEFINE_STACK_OF_IMPL(name, type *, const type *) \ BORINGSSL_DEFINE_STACK_TRAITS(name, type, false) -// DEFINE_STACK_OF defines |STACK_OF(type)| to be a stack whose elements are -// |type| *. This macro makes the |sk_type_*| functions available. +// DEFINE_STACK_OF defines `STACK_OF(type)` to be a stack whose elements are +// `type` *. This macro makes the `sk_type_*` functions available. // -// It is not necessary to use |DECLARE_STACK_OF| in files which use this macro. +// It is not necessary to use `DECLARE_STACK_OF` in files which use this macro. // // Must be used from the global namespace. #define DEFINE_STACK_OF(type) DEFINE_NAMED_STACK_OF(type, type) -// DEFINE_CONST_STACK_OF defines |STACK_OF(type)| to be a stack whose elements -// are const |type| *. This macro makes the |sk_type_*| functions available. +// DEFINE_CONST_STACK_OF defines `STACK_OF(type)` to be a stack whose elements +// are const `type` *. This macro makes the `sk_type_*` functions available. // -// It is not necessary to use |DECLARE_STACK_OF| in files which use this macro. +// It is not necessary to use `DECLARE_STACK_OF` in files which use this macro. // // Must be used from the global namespace. #define DEFINE_CONST_STACK_OF(type) \ BORINGSSL_DEFINE_STACK_OF_IMPL(type, const type *, const type *) \ BORINGSSL_DEFINE_STACK_TRAITS(type, const type, true) -// DEFINE_NAMESPACED_STACK_OF is same as |DEFINE_STACK_OF| but to be used for +// DEFINE_NAMESPACED_STACK_OF is same as `DEFINE_STACK_OF` but to be used for // internal stacks from within the bssl namespace. // -// Such stacks then can only be accessed using |STACK_OF| if in the |bssl| -// namespace or if the |bssl| namespace has been imported with a +// Such stacks then can only be accessed using `STACK_OF` if in the `bssl` +// namespace or if the `bssl` namespace has been imported with a // using-directive. #define DEFINE_NAMESPACED_STACK_OF(type) \ BORINGSSL_DEFINE_STACK_OF_IMPL(type, type *, const type *) \ @@ -86,7 +86,7 @@ // Using stacks. // -// After the |DEFINE_STACK_OF| macro is used, the following functions are +// After the `DEFINE_STACK_OF` macro is used, the following functions are // available. #if 0 // Sample @@ -98,11 +98,11 @@ // return the copy or NULL on error. typedef SAMPLE *(*sk_SAMPLE_copy_func)(const SAMPLE *); -// sk_SAMPLE_cmp_func is a callback to compare |*a| to |*b|. It should return a -// value < 0, 0, or > 0 if |*a| is less than, equal to, or greater than |*b|, +// sk_SAMPLE_cmp_func is a callback to compare `*a` to `*b`. It should return a +// value < 0, 0, or > 0 if `*a` is less than, equal to, or greater than `*b`, // respectively. Note the extra indirection - the function is given a pointer -// to a pointer to the element. This is the |qsort|/|bsearch| comparison -// function applied to an array of |SAMPLE*|. +// to a pointer to the element. This is the `qsort`/`bsearch` comparison +// function applied to an array of `SAMPLE*`. typedef int (*sk_SAMPLE_cmp_func)(const SAMPLE *const *a, const SAMPLE *const *b); @@ -114,113 +114,113 @@ // NULL on allocation failure. STACK_OF(SAMPLE) *sk_SAMPLE_new_null(void); -// sk_SAMPLE_num returns the number of elements in |sk|. It is safe to cast this -// value to |int|. |sk| is guaranteed to have at most |INT_MAX| elements. If -// |sk| is NULL, it is treated as the empty list and this function returns zero. +// sk_SAMPLE_num returns the number of elements in `sk`. It is safe to cast this +// value to `int`. `sk` is guaranteed to have at most `INT_MAX` elements. If +// `sk` is NULL, it is treated as the empty list and this function returns zero. size_t sk_SAMPLE_num(const STACK_OF(SAMPLE) *sk); -// sk_SAMPLE_zero resets |sk| to the empty state but does nothing to free the +// sk_SAMPLE_zero resets `sk` to the empty state but does nothing to free the // individual elements themselves. void sk_SAMPLE_zero(STACK_OF(SAMPLE) *sk); -// sk_SAMPLE_value returns the |i|th pointer in |sk|, or NULL if |i| is out of -// range. If |sk| is NULL, it is treated as an empty list and the function +// sk_SAMPLE_value returns the `i`th pointer in `sk`, or NULL if `i` is out of +// range. If `sk` is NULL, it is treated as an empty list and the function // returns NULL. SAMPLE *sk_SAMPLE_value(const STACK_OF(SAMPLE) *sk, size_t i); -// sk_SAMPLE_set sets the |i|th pointer in |sk| to |p| and returns |p|. If |i| +// sk_SAMPLE_set sets the `i`th pointer in `sk` to `p` and returns `p`. If `i` // is out of range, it returns NULL. SAMPLE *sk_SAMPLE_set(STACK_OF(SAMPLE) *sk, size_t i, SAMPLE *p); -// sk_SAMPLE_free frees |sk|, but does nothing to free the individual elements. -// Use |sk_SAMPLE_pop_free| to also free the elements. +// sk_SAMPLE_free frees `sk`, but does nothing to free the individual elements. +// Use `sk_SAMPLE_pop_free` to also free the elements. void sk_SAMPLE_free(STACK_OF(SAMPLE) *sk); -// sk_SAMPLE_pop_free calls |free_func| on each element in |sk| and then +// sk_SAMPLE_pop_free calls `free_func` on each element in `sk` and then // frees the stack itself. void sk_SAMPLE_pop_free(STACK_OF(SAMPLE) *sk, sk_SAMPLE_free_func free_func); -// sk_SAMPLE_insert inserts |p| into the stack at index |where|, moving existing +// sk_SAMPLE_insert inserts `p` into the stack at index `where`, moving existing // elements if needed. It returns the length of the new stack, or zero on // error. size_t sk_SAMPLE_insert(STACK_OF(SAMPLE) *sk, SAMPLE *p, size_t where); -// sk_SAMPLE_delete removes the pointer at index |where|, moving other elements -// down if needed. It returns the removed pointer, or NULL if |where| is out of +// sk_SAMPLE_delete removes the pointer at index `where`, moving other elements +// down if needed. It returns the removed pointer, or NULL if `where` is out of // range. SAMPLE *sk_SAMPLE_delete(STACK_OF(SAMPLE) *sk, size_t where); -// sk_SAMPLE_delete_ptr removes, at most, one instance of |p| from |sk| based on -// pointer equality. If an instance of |p| is found then |p| is returned, +// sk_SAMPLE_delete_ptr removes, at most, one instance of `p` from `sk` based on +// pointer equality. If an instance of `p` is found then `p` is returned, // otherwise it returns NULL. SAMPLE *sk_SAMPLE_delete_ptr(STACK_OF(SAMPLE) *sk, const SAMPLE *p); -// sk_SAMPLE_delete_if_func is the callback function for |sk_SAMPLE_delete_if|. -// It should return one to remove |p| and zero to keep it. +// sk_SAMPLE_delete_if_func is the callback function for `sk_SAMPLE_delete_if`. +// It should return one to remove `p` and zero to keep it. typedef int (*sk_SAMPLE_delete_if_func)(SAMPLE *p, void *data); -// sk_SAMPLE_delete_if calls |func| with each element of |sk| and removes the -// entries where |func| returned one. This function does not free or return -// removed pointers so, if |sk| owns its contents, |func| should release the +// sk_SAMPLE_delete_if calls `func` with each element of `sk` and removes the +// entries where `func` returned one. This function does not free or return +// removed pointers so, if `sk` owns its contents, `func` should release the // pointers prior to returning one. void sk_SAMPLE_delete_if(STACK_OF(SAMPLE) *sk, sk_SAMPLE_delete_if_func func, void *data); -// sk_SAMPLE_find find the first value in |sk| equal to |p|. |sk|'s comparison -// function determines equality, or pointer equality if |sk| has no comparison +// sk_SAMPLE_find find the first value in `sk` equal to `p`. `sk`'s comparison +// function determines equality, or pointer equality if `sk` has no comparison // function. // -// If the stack is sorted (see |sk_SAMPLE_sort|), this function uses a binary +// If the stack is sorted (see `sk_SAMPLE_sort`), this function uses a binary // search. Otherwise it performs a linear search. If it finds a matching -// element, it writes the index to |*out_index| (if |out_index| is not NULL) and -// returns one. Otherwise, it returns zero. If |sk| is NULL, it is treated as +// element, it writes the index to `*out_index` (if `out_index` is not NULL) and +// returns one. Otherwise, it returns zero. If `sk` is NULL, it is treated as // the empty list and the function returns zero. // // Note this differs from OpenSSL. The type signature is slightly different, and -// OpenSSL's version will implicitly sort |sk| if it has a comparison function +// OpenSSL's version will implicitly sort `sk` if it has a comparison function // defined. int sk_SAMPLE_find(const STACK_OF(SAMPLE) *sk, size_t *out_index, const SAMPLE *p); -// sk_SAMPLE_shift removes and returns the first element in |sk|, or NULL if -// |sk| is empty. +// sk_SAMPLE_shift removes and returns the first element in `sk`, or NULL if +// `sk` is empty. SAMPLE *sk_SAMPLE_shift(STACK_OF(SAMPLE) *sk); -// sk_SAMPLE_push appends |p| to |sk| and returns the length of the new stack, +// sk_SAMPLE_push appends `p` to `sk` and returns the length of the new stack, // or 0 on allocation failure. size_t sk_SAMPLE_push(STACK_OF(SAMPLE) *sk, SAMPLE *p); -// sk_SAMPLE_pop removes and returns the last element of |sk|, or NULL if |sk| +// sk_SAMPLE_pop removes and returns the last element of `sk`, or NULL if `sk` // is empty. SAMPLE *sk_SAMPLE_pop(STACK_OF(SAMPLE) *sk); // sk_SAMPLE_dup performs a shallow copy of a stack and returns the new stack, -// or NULL on error. Use |sk_SAMPLE_deep_copy| to also copy the elements. +// or NULL on error. Use `sk_SAMPLE_deep_copy` to also copy the elements. STACK_OF(SAMPLE) *sk_SAMPLE_dup(const STACK_OF(SAMPLE) *sk); -// sk_SAMPLE_sort sorts the elements of |sk| into ascending order based on the +// sk_SAMPLE_sort sorts the elements of `sk` into ascending order based on the // comparison function. The stack maintains a "sorted" flag and sorting an // already sorted stack is a no-op. void sk_SAMPLE_sort(STACK_OF(SAMPLE) *sk); -// sk_SAMPLE_sort_and_dedup sorts the elements of |sk| based on the comparison -// function and removes duplicates. If |free_func| is not NULL, it is called on +// sk_SAMPLE_sort_and_dedup sorts the elements of `sk` based on the comparison +// function and removes duplicates. If `free_func` is not NULL, it is called on // every removed element. void sk_SAMPLE_sort_and_dedup(STACK_OF(SAMPLE) *sk, sk_SAMPLE_free_func free_func); -// sk_SAMPLE_is_sorted returns one if |sk| is known to be sorted and zero +// sk_SAMPLE_is_sorted returns one if `sk` is known to be sorted and zero // otherwise. int sk_SAMPLE_is_sorted(const STACK_OF(SAMPLE) *sk); -// sk_SAMPLE_set_cmp_func sets the comparison function to be used by |sk| and +// sk_SAMPLE_set_cmp_func sets the comparison function to be used by `sk` and // returns the previous one. sk_SAMPLE_cmp_func sk_SAMPLE_set_cmp_func(STACK_OF(SAMPLE) *sk, sk_SAMPLE_cmp_func comp); -// sk_SAMPLE_deep_copy performs a copy of |sk| and of each of the non-NULL -// elements in |sk| by using |copy_func|. If an error occurs, it calls -// |free_func| to free any copies already made and returns NULL. +// sk_SAMPLE_deep_copy performs a copy of `sk` and of each of the non-NULL +// elements in `sk` by using `copy_func`. If an error occurs, it calls +// `free_func` to free any copies already made and returns NULL. STACK_OF(SAMPLE) *sk_SAMPLE_deep_copy(const STACK_OF(SAMPLE) *sk, sk_SAMPLE_copy_func copy_func, sk_SAMPLE_free_func free_func); @@ -230,34 +230,34 @@ // Private functions. // -// The |sk_*| functions generated above are implemented internally using the +// The `sk_*` functions generated above are implemented internally using the // type-erased functions below. Callers should use the typed wrappers instead. // When using the type-erased functions, callers are responsible for ensuring // the underlying types are correct. Casting pointers to the wrong types will // result in memory errors. // OPENSSL_sk_free_func is a function that frees an element in a stack. Note its -// actual type is void (*)(T *) for some T. Low-level |sk_*| functions will be +// actual type is void (*)(T *) for some T. Low-level `sk_*` functions will be // passed a type-specific wrapper to call it correctly. typedef void (*OPENSSL_sk_free_func)(void *ptr); // OPENSSL_sk_copy_func is a function that copies an element in a stack. Note -// its actual type is T *(*)(const T *) for some T. Low-level |sk_*| functions +// its actual type is T *(*)(const T *) for some T. Low-level `sk_*` functions // will be passed a type-specific wrapper to call it correctly. typedef void *(*OPENSSL_sk_copy_func)(const void *ptr); // OPENSSL_sk_cmp_func is a comparison function that returns a value < 0, 0 or > -// 0 if |*a| is less than, equal to or greater than |*b|, respectively. Note +// 0 if `*a` is less than, equal to or greater than `*b`, respectively. Note // the extra indirection - the function is given a pointer to a pointer to the // element. This differs from the usual qsort/bsearch comparison function. // -// Note its actual type is |int (*)(const T *const *a, const T *const *b)|. -// Low-level |sk_*| functions will be passed a type-specific wrapper to call it +// Note its actual type is `int (*)(const T *const *a, const T *const *b)`. +// Low-level `sk_*` functions will be passed a type-specific wrapper to call it // correctly. typedef int (*OPENSSL_sk_cmp_func)(const void *const *a, const void *const *b); // OPENSSL_sk_delete_if_func is the generic version of -// |sk_SAMPLE_delete_if_func|. +// `sk_SAMPLE_delete_if_func`. typedef int (*OPENSSL_sk_delete_if_func)(void *obj, void *data); // The following function types call the above type-erased signatures with the @@ -274,7 +274,7 @@ typedef struct stack_st OPENSSL_STACK; // The following are raw stack functions. They implement the corresponding typed -// |sk_SAMPLE_*| functions generated by |DEFINE_STACK_OF|. Callers shouldn't be +// `sk_SAMPLE_*` functions generated by `DEFINE_STACK_OF`. Callers shouldn't be // using them. Rather, callers should use the typed functions. OPENSSL_EXPORT OPENSSL_STACK *OPENSSL_sk_new(OPENSSL_sk_cmp_func comp); OPENSSL_EXPORT OPENSSL_STACK *OPENSSL_sk_new_null(void); @@ -324,7 +324,7 @@ typedef OPENSSL_STACK _STACK; -// The following functions call the corresponding |OPENSSL_sk_*| function. +// The following functions call the corresponding `OPENSSL_sk_*` function. OPENSSL_EXPORT OPENSSL_DEPRECATED OPENSSL_STACK *sk_new_null(void); OPENSSL_EXPORT OPENSSL_DEPRECATED size_t sk_num(const OPENSSL_STACK *sk); OPENSSL_EXPORT OPENSSL_DEPRECATED void *sk_value(const OPENSSL_STACK *sk, @@ -333,16 +333,16 @@ OPENSSL_EXPORT OPENSSL_DEPRECATED size_t sk_push(OPENSSL_STACK *sk, void *p); OPENSSL_EXPORT OPENSSL_DEPRECATED void *sk_pop(OPENSSL_STACK *sk); -// sk_pop_free_ex calls |OPENSSL_sk_pop_free_ex|. +// sk_pop_free_ex calls `OPENSSL_sk_pop_free_ex`. // // TODO(b/291994116): Remove this. OPENSSL_EXPORT OPENSSL_DEPRECATED void sk_pop_free_ex( OPENSSL_STACK *sk, OPENSSL_sk_call_free_func call_free_func, OPENSSL_sk_free_func free_func); -// sk_pop_free behaves like |OPENSSL_sk_pop_free_ex| but performs an invalid +// sk_pop_free behaves like `OPENSSL_sk_pop_free_ex` but performs an invalid // function pointer cast. It exists because some existing callers called -// |sk_pop_free| directly. +// `sk_pop_free` directly. // // TODO(davidben): Migrate callers to bssl::UniquePtr and remove this. OPENSSL_EXPORT OPENSSL_DEPRECATED void sk_pop_free( @@ -381,9 +381,9 @@ /* We disable MSVC C4191 in this macro, which warns when pointers are cast \ * to the wrong type. While the cast itself is valid, it is often a bug \ * because calling it through the cast is UB. However, we never actually \ - * call functions as |OPENSSL_sk_cmp_func|. The type is just a type-erased \ + * call functions as `OPENSSL_sk_cmp_func`. The type is just a type-erased \ * function pointer. (C does not guarantee function pointers fit in \ - * |void*|, and GCC will warn on this.) Thus we just disable the false \ + * `void*`, and GCC will warn on this.) Thus we just disable the false \ * positive warning. */ \ OPENSSL_MSVC_PRAGMA(warning(push)) \ OPENSSL_MSVC_PRAGMA(warning(disable : 4191)) \ @@ -419,7 +419,7 @@ const void *a, const void *b) { \ constptrtype a_ptr = (constptrtype)a; \ constptrtype b_ptr = (constptrtype)b; \ - /* |cmp_func| expects an extra layer of pointers to match qsort. */ \ + /* `cmp_func` expects an extra layer of pointers to match qsort. */ \ return ((sk_##name##_cmp_func)cmp_func)(&a_ptr, &b_ptr); \ } \ \ @@ -564,7 +564,7 @@ namespace internal { -// Stacks defined with |DEFINE_CONST_STACK_OF| are freed with |sk_free|. +// Stacks defined with `DEFINE_CONST_STACK_OF` are freed with `sk_free`. template <typename Stack> struct DeleterImpl<Stack, std::enable_if_t<StackTraits<Stack>::kIsConst>> { static void Free(Stack *sk) { @@ -572,7 +572,7 @@ } }; -// Stacks defined with |DEFINE_STACK_OF| are freed with |sk_pop_free| and the +// Stacks defined with `DEFINE_STACK_OF` are freed with `sk_pop_free` and the // corresponding type's deleter. template <typename Stack> struct DeleterImpl<Stack, std::enable_if_t<!StackTraits<Stack>::kIsConst>> { @@ -631,7 +631,7 @@ } // namespace internal -// PushToStack pushes |elem| to |sk|. It returns true on success and false on +// PushToStack pushes `elem` to `sk`. It returns true on success and false on // allocation failure. template <typename Stack> inline std::enable_if_t<!internal::StackTraits<Stack>::kIsConst, bool>
diff --git a/include/openssl/tls1.h b/include/openssl/tls1.h index c3e4098..f4b3484 100644 --- a/include/openssl/tls1.h +++ b/include/openssl/tls1.h
@@ -85,8 +85,8 @@ #define TLSEXT_TYPE_quic_transport_parameters 57 // TLSEXT_TYPE_quic_transport_parameters_standard is an alias for -// |TLSEXT_TYPE_quic_transport_parameters|. Use -// |TLSEXT_TYPE_quic_transport_parameters| instead. +// `TLSEXT_TYPE_quic_transport_parameters`. Use +// `TLSEXT_TYPE_quic_transport_parameters` instead. #define TLSEXT_TYPE_quic_transport_parameters_standard \ TLSEXT_TYPE_quic_transport_parameters @@ -180,7 +180,7 @@ // The following constants are equal to TLS cipher suite values, OR-d with // 0x03000000. This is part of OpenSSL's SSL 2.0 legacy. SSL 2.0 has long since // been removed from BoringSSL. -// TODO(davidben): Define these in terms of |SSL_CIPHER_*| constants. The +// TODO(davidben): Define these in terms of `SSL_CIPHER_*` constants. The // challenge is that existing code expects them to be defined in tls1.h, so we // must first merge tls1.h into ssl.h. #define TLS1_CK_PSK_WITH_AES_128_CBC_SHA 0x0300008C @@ -208,15 +208,15 @@ #define TLS1_3_CK_AES_256_GCM_SHA384 0x03001302 #define TLS1_3_CK_CHACHA20_POLY1305_SHA256 0x03001303 -// The following constants are legacy aliases of |TLS1_3_CK_*|. +// The following constants are legacy aliases of `TLS1_3_CK_*`. // TODO(davidben): Migrate callers to the new name and remove these. #define TLS1_CK_AES_128_GCM_SHA256 TLS1_3_CK_AES_128_GCM_SHA256 #define TLS1_CK_AES_256_GCM_SHA384 TLS1_3_CK_AES_256_GCM_SHA384 #define TLS1_CK_CHACHA20_POLY1305_SHA256 TLS1_3_CK_CHACHA20_POLY1305_SHA256 -// The following constants are the OpenSSL names (see |SSL_CIPHER_get_name|) for +// The following constants are the OpenSSL names (see `SSL_CIPHER_get_name`) for // various TLS ciphers. Prefer the standard name, returned from -// |SSL_CIPHER_standard_name| and supported by |SSL_CTX_set_cipher_list|. +// `SSL_CIPHER_standard_name` and supported by `SSL_CTX_set_cipher_list`. #define TLS1_TXT_PSK_WITH_AES_128_CBC_SHA "PSK-AES128-CBC-SHA" #define TLS1_TXT_PSK_WITH_AES_256_CBC_SHA "PSK-AES256-CBC-SHA" #define TLS1_TXT_ECDHE_PSK_WITH_AES_128_CBC_SHA "ECDHE-PSK-AES128-CBC-SHA"
diff --git a/include/openssl/tls_prf.h b/include/openssl/tls_prf.h index 4740d02..83ce9a6 100644 --- a/include/openssl/tls_prf.h +++ b/include/openssl/tls_prf.h
@@ -27,10 +27,10 @@ // The TLS PRF is defined in Section 5 of RFC 5246. -// CRYPTO_tls1_prf calculates |out_len| bytes of the TLS PRF, using |digest|, -// and writes them to |out|. It is defined in Section 5 of RFC 5246, acting on -// |secret_len| bytes of shared |secret|, |label_len| bytes of |label|, -// |seed1_len| bytes of |seed1| and |seed2_len| bytes of |seed2|. It returns one +// CRYPTO_tls1_prf calculates `out_len` bytes of the TLS PRF, using `digest`, +// and writes them to `out`. It is defined in Section 5 of RFC 5246, acting on +// `secret_len` bytes of shared `secret`, `label_len` bytes of `label`, +// `seed1_len` bytes of `seed1` and `seed2_len` bytes of `seed2`. It returns one // on success and zero on error. OPENSSL_EXPORT int CRYPTO_tls1_prf(const EVP_MD *digest, uint8_t *out, size_t out_len, const uint8_t *secret,
diff --git a/include/openssl/trust_token.h b/include/openssl/trust_token.h index e9c4667..cf909ae 100644 --- a/include/openssl/trust_token.h +++ b/include/openssl/trust_token.h
@@ -67,25 +67,25 @@ DEFINE_STACK_OF(TRUST_TOKEN) -// TRUST_TOKEN_new creates a newly-allocated |TRUST_TOKEN| with value |data| or +// TRUST_TOKEN_new creates a newly-allocated `TRUST_TOKEN` with value `data` or // NULL on allocation failure. OPENSSL_EXPORT TRUST_TOKEN *TRUST_TOKEN_new(const uint8_t *data, size_t len); -// TRUST_TOKEN_free releases memory associated with |token|. +// TRUST_TOKEN_free releases memory associated with `token`. OPENSSL_EXPORT void TRUST_TOKEN_free(TRUST_TOKEN *token); #define TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE 512 #define TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE 512 -// TRUST_TOKEN_generate_key creates a new Trust Token keypair labeled with |id| +// TRUST_TOKEN_generate_key creates a new Trust Token keypair labeled with `id` // and serializes the private and public keys, writing the private key to -// |out_priv_key| and setting |*out_priv_key_len| to the number of bytes -// written, and writing the public key to |out_pub_key| and setting -// |*out_pub_key_len| to the number of bytes written. +// `out_priv_key` and setting `*out_priv_key_len` to the number of bytes +// written, and writing the public key to `out_pub_key` and setting +// `*out_pub_key_len` to the number of bytes written. // -// At most |max_priv_key_len| and |max_pub_key_len| bytes are written. In order +// At most `max_priv_key_len` and `max_pub_key_len` bytes are written. In order // to ensure success, these should be at least -// |TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE| and |TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE|. +// `TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE` and `TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE`. // // This function returns one on success or zero on error. OPENSSL_EXPORT int TRUST_TOKEN_generate_key( @@ -94,15 +94,15 @@ size_t *out_pub_key_len, size_t max_pub_key_len, uint32_t id); // TRUST_TOKEN_derive_key_from_secret deterministically derives a new Trust -// Token keypair labeled with |id| from an input |secret| and serializes the -// private and public keys, writing the private key to |out_priv_key| and -// setting |*out_priv_key_len| to the number of bytes written, and writing the -// public key to |out_pub_key| and setting |*out_pub_key_len| to the number of +// Token keypair labeled with `id` from an input `secret` and serializes the +// private and public keys, writing the private key to `out_priv_key` and +// setting `*out_priv_key_len` to the number of bytes written, and writing the +// public key to `out_pub_key` and setting `*out_pub_key_len` to the number of // bytes written. // -// At most |max_priv_key_len| and |max_pub_key_len| bytes are written. In order +// At most `max_priv_key_len` and `max_pub_key_len` bytes are written. In order // to ensure success, these should be at least -// |TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE| and |TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE|. +// `TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE` and `TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE`. // // This function returns one on success or zero on error. OPENSSL_EXPORT int TRUST_TOKEN_derive_key_from_secret( @@ -115,34 +115,34 @@ // Trust Token client implementation. // // These functions implements the client half of the Trust Token protocol. A -// single |TRUST_TOKEN_CLIENT| can perform a single protocol operation. +// single `TRUST_TOKEN_CLIENT` can perform a single protocol operation. -// TRUST_TOKEN_CLIENT_new returns a newly-allocated |TRUST_TOKEN_CLIENT| -// configured to use a max batchsize of |max_batchsize| or NULL on error. -// Issuance requests must be made in batches smaller than |max_batchsize|. This -// function will return an error if |max_batchsize| is too large for Trust +// TRUST_TOKEN_CLIENT_new returns a newly-allocated `TRUST_TOKEN_CLIENT` +// configured to use a max batchsize of `max_batchsize` or NULL on error. +// Issuance requests must be made in batches smaller than `max_batchsize`. This +// function will return an error if `max_batchsize` is too large for Trust // Tokens. OPENSSL_EXPORT TRUST_TOKEN_CLIENT *TRUST_TOKEN_CLIENT_new( const TRUST_TOKEN_METHOD *method, size_t max_batchsize); -// TRUST_TOKEN_CLIENT_free releases memory associated with |ctx|. +// TRUST_TOKEN_CLIENT_free releases memory associated with `ctx`. OPENSSL_EXPORT void TRUST_TOKEN_CLIENT_free(TRUST_TOKEN_CLIENT *ctx); -// TRUST_TOKEN_CLIENT_dup_for_testing returns a newly-allocated copy of |ctx|, +// TRUST_TOKEN_CLIENT_dup_for_testing returns a newly-allocated copy of `ctx`, // or NULL on error. This may be useful for testing the library, e.g. to // benchmark an individual operation. // // WARNING: This function should never be used in production. A -// |TRUST_TOKEN_CLIENT| maintains single-use state between -// |TRUST_TOKEN_CLIENT_begin_issuance| and |TRUST_TOKEN_CLIENT_finish_issuance| +// `TRUST_TOKEN_CLIENT` maintains single-use state between +// `TRUST_TOKEN_CLIENT_begin_issuance` and `TRUST_TOKEN_CLIENT_finish_issuance` // operations. Cloning this state will cause tokens to be linkable and no longer // anonymized. OPENSSL_EXPORT TRUST_TOKEN_CLIENT *TRUST_TOKEN_CLIENT_dup_for_testing( const TRUST_TOKEN_CLIENT *ctx); -// TRUST_TOKEN_CLIENT_add_key configures the |ctx| to support the public key -// |key|. It sets |*out_key_index| to the index this key has been configured to. -// It returns one on success or zero on error if the |key| can't be parsed or +// TRUST_TOKEN_CLIENT_add_key configures the `ctx` to support the public key +// `key`. It sets `*out_key_index` to the index this key has been configured to. +// It returns one on success or zero on error if the `key` can't be parsed or // too many keys have been configured. OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_add_key(TRUST_TOKEN_CLIENT *ctx, size_t *out_key_index, @@ -154,10 +154,10 @@ OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_set_srr_key(TRUST_TOKEN_CLIENT *ctx, EVP_PKEY *key); -// TRUST_TOKEN_CLIENT_begin_issuance produces a request for |count| trust tokens -// and serializes the request into a newly-allocated buffer, setting |*out| to -// that buffer and |*out_len| to its length. The caller takes ownership of the -// buffer and must call |OPENSSL_free| when done. It returns one on success and +// TRUST_TOKEN_CLIENT_begin_issuance produces a request for `count` trust tokens +// and serializes the request into a newly-allocated buffer, setting `*out` to +// that buffer and `*out_len` to its length. The caller takes ownership of the +// buffer and must call `OPENSSL_free` when done. It returns one on success and // zero on error. OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_issuance(TRUST_TOKEN_CLIENT *ctx, uint8_t **out, @@ -165,20 +165,20 @@ size_t count); // TRUST_TOKEN_CLIENT_begin_issuance_over_message produces a request for a trust -// token derived from |msg| and serializes the request into a newly-allocated -// buffer, setting |*out| to that buffer and |*out_len| to its length. The -// caller takes ownership of the buffer and must call |OPENSSL_free| when done. +// token derived from `msg` and serializes the request into a newly-allocated +// buffer, setting `*out` to that buffer and `*out_len` to its length. The +// caller takes ownership of the buffer and must call `OPENSSL_free` when done. // It returns one on success and zero on error. OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_issuance_over_message( TRUST_TOKEN_CLIENT *ctx, uint8_t **out, size_t *out_len, size_t count, const uint8_t *msg, size_t msg_len); -// TRUST_TOKEN_CLIENT_finish_issuance consumes |response| from the issuer and +// TRUST_TOKEN_CLIENT_finish_issuance consumes `response` from the issuer and // extracts the tokens, returning a list of tokens and the index of the key used -// to sign the tokens in |*out_key_index|. The caller can use this to determine +// to sign the tokens in `*out_key_index`. The caller can use this to determine // what key was used in an issuance and to drop tokens if a new key commitment // arrives without the specified key present. The caller takes ownership of the -// list and must call |sk_TRUST_TOKEN_pop_free| when done. The list is empty if +// list and must call `sk_TRUST_TOKEN_pop_free` when done. The list is empty if // issuance fails. OPENSSL_EXPORT STACK_OF(TRUST_TOKEN) * TRUST_TOKEN_CLIENT_finish_issuance(TRUST_TOKEN_CLIENT *ctx, @@ -188,23 +188,23 @@ // TRUST_TOKEN_CLIENT_begin_redemption produces a request to redeem a token -// |token| and receive a signature over |data| and serializes the request into -// a newly-allocated buffer, setting |*out| to that buffer and |*out_len| to -// its length. |time| is the number of seconds since the UNIX epoch and used to +// `token` and receive a signature over `data` and serializes the request into +// a newly-allocated buffer, setting `*out` to that buffer and `*out_len` to +// its length. `time` is the number of seconds since the UNIX epoch and used to // verify the validity of the issuer's response in TrustTokenV1 and ignored in // other versions. The caller takes ownership of the buffer and must call -// |OPENSSL_free| when done. It returns one on success or zero on error. +// `OPENSSL_free` when done. It returns one on success or zero on error. OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_redemption( TRUST_TOKEN_CLIENT *ctx, uint8_t **out, size_t *out_len, const TRUST_TOKEN *token, const uint8_t *data, size_t data_len, uint64_t time); -// TRUST_TOKEN_CLIENT_finish_redemption consumes |response| from the issuer. In -// |TRUST_TOKEN_experiment_v1|, it then verifies the SRR and if valid sets -// |*out_rr| and |*out_rr_len| (respectively, |*out_sig| and |*out_sig_len|) +// TRUST_TOKEN_CLIENT_finish_redemption consumes `response` from the issuer. In +// `TRUST_TOKEN_experiment_v1`, it then verifies the SRR and if valid sets +// `*out_rr` and `*out_rr_len` (respectively, `*out_sig` and `*out_sig_len`) // to a newly-allocated buffer containing the SRR (respectively, the SRR -// signature). In other versions, it sets |*out_rr| and |*out_rr_len| -// to a newly-allocated buffer containing |response| and leaves all validation +// signature). In other versions, it sets `*out_rr` and `*out_rr_len` +// to a newly-allocated buffer containing `response` and leaves all validation // to the caller. It returns one on success or zero on failure. OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_finish_redemption( TRUST_TOKEN_CLIENT *ctx, uint8_t **out_rr, size_t *out_rr_len, @@ -215,26 +215,26 @@ // Trust Token issuer implementation. // // These functions implement the issuer half of the Trust Token protocol. A -// |TRUST_TOKEN_ISSUER| can be reused across multiple protocol operations. It +// `TRUST_TOKEN_ISSUER` can be reused across multiple protocol operations. It // may be used concurrently on multiple threads by non-mutating functions, // provided no other thread is concurrently calling a mutating function. -// Functions which take a |const| pointer are non-mutating and functions which -// take a non-|const| pointer are mutating. +// Functions which take a `const` pointer are non-mutating and functions which +// take a non-`const` pointer are mutating. -// TRUST_TOKEN_ISSUER_new returns a newly-allocated |TRUST_TOKEN_ISSUER| -// configured to use a max batchsize of |max_batchsize| or NULL on error. -// Issuance requests must be made in batches smaller than |max_batchsize|. This -// function will return an error if |max_batchsize| is too large for Trust +// TRUST_TOKEN_ISSUER_new returns a newly-allocated `TRUST_TOKEN_ISSUER` +// configured to use a max batchsize of `max_batchsize` or NULL on error. +// Issuance requests must be made in batches smaller than `max_batchsize`. This +// function will return an error if `max_batchsize` is too large for Trust // Tokens. OPENSSL_EXPORT TRUST_TOKEN_ISSUER *TRUST_TOKEN_ISSUER_new( const TRUST_TOKEN_METHOD *method, size_t max_batchsize); -// TRUST_TOKEN_ISSUER_free releases memory associated with |ctx|. +// TRUST_TOKEN_ISSUER_free releases memory associated with `ctx`. OPENSSL_EXPORT void TRUST_TOKEN_ISSUER_free(TRUST_TOKEN_ISSUER *ctx); -// TRUST_TOKEN_ISSUER_add_key configures the |ctx| to support the private key -// |key|. It must be a private key returned by |TRUST_TOKEN_generate_key|. It -// returns one on success or zero on error. This function may fail if the |key| +// TRUST_TOKEN_ISSUER_add_key configures the `ctx` to support the private key +// `key`. It must be a private key returned by `TRUST_TOKEN_generate_key`. It +// returns one on success or zero on error. This function may fail if the `key` // can't be parsed or too many keys have been configured. OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_add_key(TRUST_TOKEN_ISSUER *ctx, const uint8_t *key, @@ -245,31 +245,31 @@ OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_set_srr_key(TRUST_TOKEN_ISSUER *ctx, EVP_PKEY *key); -// TRUST_TOKEN_ISSUER_issue ingests |request| for token issuance -// and generates up to |max_issuance| valid tokens, producing a list of blinded +// TRUST_TOKEN_ISSUER_issue ingests `request` for token issuance +// and generates up to `max_issuance` valid tokens, producing a list of blinded // tokens and storing the response into a newly-allocated buffer and setting -// |*out| to that buffer, |*out_len| to its length, and |*out_tokens_issued| to +// `*out` to that buffer, `*out_len` to its length, and `*out_tokens_issued` to // the number of tokens issued. The tokens are issued with public metadata of -// |public_metadata| and a private metadata value of |private_metadata|. -// |public_metadata| must be one of the previously configured key IDs. -// |private_metadata| must be 0 or 1. The caller takes ownership of the buffer -// and must call |OPENSSL_free| when done. It returns one on success or zero on +// `public_metadata` and a private metadata value of `private_metadata`. +// `public_metadata` must be one of the previously configured key IDs. +// `private_metadata` must be 0 or 1. The caller takes ownership of the buffer +// and must call `OPENSSL_free` when done. It returns one on success or zero on // error. OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_issue( const TRUST_TOKEN_ISSUER *ctx, uint8_t **out, size_t *out_len, size_t *out_tokens_issued, const uint8_t *request, size_t request_len, uint32_t public_metadata, uint8_t private_metadata, size_t max_issuance); -// TRUST_TOKEN_ISSUER_redeem ingests a |request| for token redemption and -// verifies the token. The public metadata is stored in |*out_public|. The -// private metadata (if any) is stored in |*out_private|. The extracted -// |TRUST_TOKEN| is stored into a newly-allocated buffer and stored in -// |*out_token|. The extracted client data is stored into a newly-allocated -// buffer and stored in |*out_client_data|. The caller takes ownership of each -// output buffer and must call |OPENSSL_free| when done. It returns one on +// TRUST_TOKEN_ISSUER_redeem ingests a `request` for token redemption and +// verifies the token. The public metadata is stored in `*out_public`. The +// private metadata (if any) is stored in `*out_private`. The extracted +// `TRUST_TOKEN` is stored into a newly-allocated buffer and stored in +// `*out_token`. The extracted client data is stored into a newly-allocated +// buffer and stored in `*out_client_data`. The caller takes ownership of each +// output buffer and must call `OPENSSL_free` when done. It returns one on // success or zero on error. // -// The caller must keep track of all values of |*out_token| seen globally before +// The caller must keep track of all values of `*out_token` seen globally before // returning a response to the client. If the value has been reused, the caller // must report an error to the client. Returning a response with replayed values // allows an attacker to double-spend tokens. @@ -279,20 +279,20 @@ size_t *out_client_data_len, const uint8_t *request, size_t request_len); // TRUST_TOKEN_ISSUER_redeem_raw is a legacy alias for -// |TRUST_TOKEN_ISSUER_redeem|. +// `TRUST_TOKEN_ISSUER_redeem`. #define TRUST_TOKEN_ISSUER_redeem_raw TRUST_TOKEN_ISSUER_redeem -// TRUST_TOKEN_ISSUER_redeem_over_message ingests a |request| for token +// TRUST_TOKEN_ISSUER_redeem_over_message ingests a `request` for token // redemption and a message and verifies the token and that it is derived from -// the provided |msg|. The public metadata is stored in -// |*out_public|. The private metadata (if any) is stored in |*out_private|. The -// extracted |TRUST_TOKEN| is stored into a newly-allocated buffer and stored in -// |*out_token|. The extracted client data is stored into a newly-allocated -// buffer and stored in |*out_client_data|. The caller takes ownership of each -// output buffer and must call |OPENSSL_free| when done. It returns one on +// the provided `msg`. The public metadata is stored in +// `*out_public`. The private metadata (if any) is stored in `*out_private`. The +// extracted `TRUST_TOKEN` is stored into a newly-allocated buffer and stored in +// `*out_token`. The extracted client data is stored into a newly-allocated +// buffer and stored in `*out_client_data`. The caller takes ownership of each +// output buffer and must call `OPENSSL_free` when done. It returns one on // success or zero on error. // -// The caller must keep track of all values of |*out_token| seen globally before +// The caller must keep track of all values of `*out_token` seen globally before // returning a response to the client. If the value has been reused, the caller // must report an error to the client. Returning a response with replayed values // allows an attacker to double-spend tokens. @@ -302,10 +302,10 @@ size_t *out_client_data_len, const uint8_t *request, size_t request_len, const uint8_t *msg, size_t msg_len); -// TRUST_TOKEN_decode_private_metadata decodes |encrypted_bit| using the -// private metadata key specified by a |key| buffer of length |key_len| and the -// nonce by a |nonce| buffer of length |nonce_len|. The nonce in -// |TRUST_TOKEN_experiment_v1| is the token-hash field of the SRR. |*out_value| +// TRUST_TOKEN_decode_private_metadata decodes `encrypted_bit` using the +// private metadata key specified by a `key` buffer of length `key_len` and the +// nonce by a `nonce` buffer of length `nonce_len`. The nonce in +// `TRUST_TOKEN_experiment_v1` is the token-hash field of the SRR. `*out_value` // is set to the decrypted value, either zero or one. It returns one on success // and zero on error. OPENSSL_EXPORT int TRUST_TOKEN_decode_private_metadata(
diff --git a/include/openssl/type_check.h b/include/openssl/type_check.h index 185b765..a95bf131 100644 --- a/include/openssl/type_check.h +++ b/include/openssl/type_check.h
@@ -22,7 +22,7 @@ #endif -// CHECKED_CAST casts |p| from type |from| to type |to|. +// CHECKED_CAST casts `p` from type `from` to type `to`. // // TODO(davidben): Although this macro is not public API and is unused in // BoringSSL, wpa_supplicant uses it to define its own stacks. Remove this once
diff --git a/include/openssl/x509.h b/include/openssl/x509.h index e72d9ca..da74824 100644 --- a/include/openssl/x509.h +++ b/include/openssl/x509.h
@@ -57,11 +57,11 @@ // Certificates. // -// An |X509| object represents an X.509 certificate, defined in RFC 5280. +// An `X509` object represents an X.509 certificate, defined in RFC 5280. // -// Although an |X509| is a mutable object, mutating an |X509| can give incorrect -// results. Callers typically obtain |X509|s by parsing some input with -// |d2i_X509|, etc. Such objects carry information such as the serialized +// Although an `X509` is a mutable object, mutating an `X509` can give incorrect +// results. Callers typically obtain `X509`s by parsing some input with +// `d2i_X509`, etc. Such objects carry information such as the serialized // TBSCertificate and decoded extensions, which will become inconsistent when // mutated. // @@ -70,59 +70,59 @@ DEFINE_STACK_OF(X509) -// X509 is an |ASN1_ITEM| whose ASN.1 type is X.509 Certificate (RFC 5280) and C -// type is |X509*|. +// X509 is an `ASN1_ITEM` whose ASN.1 type is X.509 Certificate (RFC 5280) and C +// type is `X509*`. DECLARE_ASN1_ITEM(X509) -// X509_up_ref adds one to the reference count of |x509| and returns one. +// X509_up_ref adds one to the reference count of `x509` and returns one. OPENSSL_EXPORT int X509_up_ref(X509 *x509); -// X509_dup_ref increments the reference count of |x509| and returns |x509|. -// The caller must call |X509_free| on the result to release the reference. +// X509_dup_ref increments the reference count of `x509` and returns `x509`. +// The caller must call `X509_free` on the result to release the reference. // -// WARNING: Although the result is non-const for use with |X509_free|, it is +// WARNING: Although the result is non-const for use with `X509_free`, it is // still shared with other parts of the appplication for the same object. Avoid -// mutating shared |X509|s. +// mutating shared `X509`s. OPENSSL_EXPORT X509 *X509_dup_ref(const X509 *x509); -// X509_chain_up_ref returns a newly-allocated |STACK_OF(X509)| containing a -// shallow copy of |chain|, or NULL on error. That is, the return value has the -// same contents as |chain|, and each |X509|'s reference count is incremented by +// X509_chain_up_ref returns a newly-allocated `STACK_OF(X509)` containing a +// shallow copy of `chain`, or NULL on error. That is, the return value has the +// same contents as `chain`, and each `X509`'s reference count is incremented by // one. OPENSSL_EXPORT STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *chain); -// X509_dup returns a newly-allocated copy of |x509|, or NULL on error. This +// X509_dup returns a newly-allocated copy of `x509`, or NULL on error. This // function works by serializing the structure, so auxiliary properties (see -// |i2d_X509_AUX|) are not preserved. Additionally, if |x509| is incomplete, +// `i2d_X509_AUX`) are not preserved. Additionally, if `x509` is incomplete, // this function may fail. OPENSSL_EXPORT X509 *X509_dup(const X509 *x509); -// X509_free decrements |x509|'s reference count and, if zero, releases memory -// associated with |x509|. +// X509_free decrements `x509`'s reference count and, if zero, releases memory +// associated with `x509`. OPENSSL_EXPORT void X509_free(X509 *x509); -// d2i_X509 parses up to |len| bytes from |*inp| as a DER-encoded X.509 -// Certificate (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_X509 parses up to `len` bytes from `*inp` as a DER-encoded X.509 +// Certificate (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509 *d2i_X509(X509 **out, const uint8_t **inp, long len); -// X509_parse_with_algorithms parses an X.509 structure from |buf| and returns a -// fresh X509 or NULL on error. There must not be any trailing data in |buf|. -// The returned structure (if any) increment's |buf|'s reference count and +// X509_parse_with_algorithms parses an X.509 structure from `buf` and returns a +// fresh X509 or NULL on error. There must not be any trailing data in `buf`. +// The returned structure (if any) increment's `buf`'s reference count and // retains a reference to it. // -// Only the |num_algs| algorithms from |algs| will be considered when parsing +// Only the `num_algs` algorithms from `algs` will be considered when parsing // the certificate's public key. If the certificate uses a different algorithm, -// it will still be parsed, but |X509_get0_pubkey| will return NULL. +// it will still be parsed, but `X509_get0_pubkey` will return NULL. OPENSSL_EXPORT X509 *X509_parse_with_algorithms(CRYPTO_BUFFER *buf, const EVP_PKEY_ALG *const *algs, size_t num_algs); -// X509_parse_from_buffer behaves like |X509_parse_with_algorithms| but uses a +// X509_parse_from_buffer behaves like `X509_parse_with_algorithms` but uses a // default algorithm list. OPENSSL_EXPORT X509 *X509_parse_from_buffer(CRYPTO_BUFFER *buf); -// i2d_X509 marshals |x509| as a DER-encoded X.509 Certificate (RFC 5280), as -// described in |i2d_SAMPLE|. +// i2d_X509 marshals `x509` as a DER-encoded X.509 Certificate (RFC 5280), as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509(const X509 *x509, uint8_t **outp); // X509_VERSION_* are X.509 version numbers. Note the numerical values of all @@ -131,65 +131,65 @@ #define X509_VERSION_2 1 #define X509_VERSION_3 2 -// X509_get_version returns the numerical value of |x509|'s version, which will -// be one of the |X509_VERSION_*| constants. +// X509_get_version returns the numerical value of `x509`'s version, which will +// be one of the `X509_VERSION_*` constants. OPENSSL_EXPORT long X509_get_version(const X509 *x509); -// X509_get0_serialNumber returns |x509|'s serial number. +// X509_get0_serialNumber returns `x509`'s serial number. OPENSSL_EXPORT const ASN1_INTEGER *X509_get0_serialNumber(const X509 *x509); -// X509_get0_notBefore returns |x509|'s notBefore time. +// X509_get0_notBefore returns `x509`'s notBefore time. OPENSSL_EXPORT const ASN1_TIME *X509_get0_notBefore(const X509 *x509); -// X509_get0_notAfter returns |x509|'s notAfter time. +// X509_get0_notAfter returns `x509`'s notAfter time. OPENSSL_EXPORT const ASN1_TIME *X509_get0_notAfter(const X509 *x509); -// X509_get_issuer_name returns |x509|'s issuer. +// X509_get_issuer_name returns `x509`'s issuer. OPENSSL_EXPORT X509_NAME *X509_get_issuer_name(const X509 *x509); -// X509_get_subject_name returns |x509|'s subject. +// X509_get_subject_name returns `x509`'s subject. OPENSSL_EXPORT X509_NAME *X509_get_subject_name(const X509 *x509); -// X509_get_X509_PUBKEY returns the public key of |x509|. Note this function is +// X509_get_X509_PUBKEY returns the public key of `x509`. Note this function is // not const-correct for legacy reasons. Callers should not modify the returned // object. OPENSSL_EXPORT X509_PUBKEY *X509_get_X509_PUBKEY(const X509 *x509); -// X509_get0_pubkey returns |x509|'s public key as an |EVP_PKEY|, or NULL if the -// public key was unsupported or could not be decoded. The |EVP_PKEY| is cached -// in |x509|, so callers must not mutate the result. +// X509_get0_pubkey returns `x509`'s public key as an `EVP_PKEY`, or NULL if the +// public key was unsupported or could not be decoded. The `EVP_PKEY` is cached +// in `x509`, so callers must not mutate the result. OPENSSL_EXPORT EVP_PKEY *X509_get0_pubkey(const X509 *x509); -// X509_get_pubkey behaves like |X509_get0_pubkey| but increments the reference -// count on the |EVP_PKEY|. The caller must release the result with -// |EVP_PKEY_free| when done. The |EVP_PKEY| is cached in |x509|, so callers +// X509_get_pubkey behaves like `X509_get0_pubkey` but increments the reference +// count on the `EVP_PKEY`. The caller must release the result with +// `EVP_PKEY_free` when done. The `EVP_PKEY` is cached in `x509`, so callers // must not mutate the result. OPENSSL_EXPORT EVP_PKEY *X509_get_pubkey(const X509 *x509); -// X509_get0_pubkey_bitstr returns the BIT STRING portion of |x509|'s public +// X509_get0_pubkey_bitstr returns the BIT STRING portion of `x509`'s public // key. Note this does not contain the AlgorithmIdentifier portion. // // WARNING: This function returns a non-const pointer for OpenSSL compatibility, // but the caller must not modify the resulting object. Doing so will break -// internal invariants in |x509|. +// internal invariants in `x509`. OPENSSL_EXPORT ASN1_BIT_STRING *X509_get0_pubkey_bitstr(const X509 *x509); -// X509_check_private_key returns one if |x509|'s public key matches |pkey| and +// X509_check_private_key returns one if `x509`'s public key matches `pkey` and // zero otherwise. OPENSSL_EXPORT int X509_check_private_key(const X509 *x509, const EVP_PKEY *pkey); -// X509_get0_uids sets |*out_issuer_uid| to a non-owning pointer to the -// issuerUID field of |x509|, or NULL if |x509| has no issuerUID. It similarly -// outputs |x509|'s subjectUID field to |*out_subject_uid|. +// X509_get0_uids sets `*out_issuer_uid` to a non-owning pointer to the +// issuerUID field of `x509`, or NULL if `x509` has no issuerUID. It similarly +// outputs `x509`'s subjectUID field to `*out_subject_uid`. // -// Callers may pass NULL to either |out_issuer_uid| or |out_subject_uid| to +// Callers may pass NULL to either `out_issuer_uid` or `out_subject_uid` to // ignore the corresponding field. OPENSSL_EXPORT void X509_get0_uids(const X509 *x509, const ASN1_BIT_STRING **out_issuer_uid, const ASN1_BIT_STRING **out_subject_uid); -// The following bits are returned from |X509_get_extension_flags|. +// The following bits are returned from `X509_get_extension_flags`. // EXFLAG_BCONS indicates the certificate has a basic constraints extension. #define EXFLAG_BCONS 0x1 @@ -220,21 +220,21 @@ // itself is not checked in computing this bit. #define EXFLAG_SS 0x2000 -// X509_get_extension_flags decodes a set of extensions from |x509| and returns -// a collection of |EXFLAG_*| bits which reflect |x509|. If there was an error -// in computing this bitmask, the result will include the |EXFLAG_INVALID| bit. +// X509_get_extension_flags decodes a set of extensions from `x509` and returns +// a collection of `EXFLAG_*` bits which reflect `x509`. If there was an error +// in computing this bitmask, the result will include the `EXFLAG_INVALID` bit. OPENSSL_EXPORT uint32_t X509_get_extension_flags(X509 *x509); // X509_get_pathlen returns path length constraint from the basic constraints -// extension in |x509|. (See RFC 5280, section 4.2.1.9.) It returns -1 if the -// constraint is not present, or if some extension in |x509| was invalid. +// extension in `x509`. (See RFC 5280, section 4.2.1.9.) It returns -1 if the +// constraint is not present, or if some extension in `x509` was invalid. // -// TODO(crbug.com/boringssl/381): Decoding an |X509| object will not check for +// TODO(crbug.com/boringssl/381): Decoding an `X509` object will not check for // invalid extensions. To detect the error case, call -// |X509_get_extension_flags| and check the |EXFLAG_INVALID| bit. +// `X509_get_extension_flags` and check the `EXFLAG_INVALID` bit. OPENSSL_EXPORT long X509_get_pathlen(X509 *x509); -// X509v3_KU_* are key usage bits returned from |X509_get_key_usage|. +// X509v3_KU_* are key usage bits returned from `X509_get_key_usage`. #define X509v3_KU_DIGITAL_SIGNATURE 0x0080 #define X509v3_KU_NON_REPUDIATION 0x0040 #define X509v3_KU_KEY_ENCIPHERMENT 0x0020 @@ -246,22 +246,22 @@ #define X509v3_KU_DECIPHER_ONLY 0x8000 // X509_get_key_usage returns a bitmask of key usages (see Section 4.2.1.3 of -// RFC 5280) which |x509| is valid for. This function only reports the first 16 +// RFC 5280) which `x509` is valid for. This function only reports the first 16 // bits, in a little-endian byte order, but big-endian bit order. That is, bits // 0 though 7 are reported at 1<<7 through 1<<0, and bits 8 through 15 are // reported at 1<<15 through 1<<8. // // Instead of depending on this bit order, callers should compare against the -// |X509v3_KU_*| constants. +// `X509v3_KU_*` constants. // -// If |x509| has no key usage extension, all key usages are valid and this -// function returns |UINT32_MAX|. If there was an error processing |x509|'s +// If `x509` has no key usage extension, all key usages are valid and this +// function returns `UINT32_MAX`. If there was an error processing `x509`'s // extensions, or if the first 16 bits in the key usage extension were all zero, // this function returns zero. OPENSSL_EXPORT uint32_t X509_get_key_usage(X509 *x509); // XKU_* are extended key usage bits returned from -// |X509_get_extended_key_usage|. +// `X509_get_extended_key_usage`. #define XKU_SSL_SERVER 0x1 #define XKU_SSL_CLIENT 0x2 #define XKU_SMIME 0x4 @@ -273,285 +273,285 @@ #define XKU_ANYEKU 0x100 // X509_get_extended_key_usage returns a bitmask of extended key usages (see -// Section 4.2.1.12 of RFC 5280) which |x509| is valid for. The result will be -// a combination of |XKU_*| constants. If checking an extended key usage not +// Section 4.2.1.12 of RFC 5280) which `x509` is valid for. The result will be +// a combination of `XKU_*` constants. If checking an extended key usage not // defined above, callers should extract the extended key usage extension -// separately, e.g. via |X509_get_ext_d2i|. +// separately, e.g. via `X509_get_ext_d2i`. // -// If |x509| has no extended key usage extension, all extended key usages are -// valid and this function returns |UINT32_MAX|. If there was an error -// processing |x509|'s extensions, or if |x509|'s extended key usage extension +// If `x509` has no extended key usage extension, all extended key usages are +// valid and this function returns `UINT32_MAX`. If there was an error +// processing `x509`'s extensions, or if `x509`'s extended key usage extension // contained no recognized usages, this function returns zero. OPENSSL_EXPORT uint32_t X509_get_extended_key_usage(X509 *x509); -// X509_get0_subject_key_id returns |x509|'s subject key identifier, if present. +// X509_get0_subject_key_id returns `x509`'s subject key identifier, if present. // (See RFC 5280, section 4.2.1.2.) It returns NULL if the extension is not -// present or if some extension in |x509| was invalid. +// present or if some extension in `x509` was invalid. // -// TODO(crbug.com/boringssl/381): Decoding an |X509| object will not check for +// TODO(crbug.com/boringssl/381): Decoding an `X509` object will not check for // invalid extensions. To detect the error case, call -// |X509_get_extension_flags| and check the |EXFLAG_INVALID| bit. +// `X509_get_extension_flags` and check the `EXFLAG_INVALID` bit. OPENSSL_EXPORT const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x509); -// X509_get0_authority_key_id returns keyIdentifier of |x509|'s authority key +// X509_get0_authority_key_id returns keyIdentifier of `x509`'s authority key // identifier, if the extension and field are present. (See RFC 5280, // section 4.2.1.1.) It returns NULL if the extension is not present, if it is -// present but lacks a keyIdentifier field, or if some extension in |x509| was +// present but lacks a keyIdentifier field, or if some extension in `x509` was // invalid. // -// TODO(crbug.com/boringssl/381): Decoding an |X509| object will not check for +// TODO(crbug.com/boringssl/381): Decoding an `X509` object will not check for // invalid extensions. To detect the error case, call -// |X509_get_extension_flags| and check the |EXFLAG_INVALID| bit. +// `X509_get_extension_flags` and check the `EXFLAG_INVALID` bit. OPENSSL_EXPORT const ASN1_OCTET_STRING *X509_get0_authority_key_id(X509 *x509); DEFINE_STACK_OF(GENERAL_NAME) typedef STACK_OF(GENERAL_NAME) GENERAL_NAMES; -// X509_get0_authority_issuer returns the authorityCertIssuer of |x509|'s +// X509_get0_authority_issuer returns the authorityCertIssuer of `x509`'s // authority key identifier, if the extension and field are present. (See // RFC 5280, section 4.2.1.1.) It returns NULL if the extension is not present, // if it is present but lacks a authorityCertIssuer field, or if some extension -// in |x509| was invalid. +// in `x509` was invalid. // -// TODO(crbug.com/boringssl/381): Decoding an |X509| object will not check for +// TODO(crbug.com/boringssl/381): Decoding an `X509` object will not check for // invalid extensions. To detect the error case, call -// |X509_get_extension_flags| and check the |EXFLAG_INVALID| bit. +// `X509_get_extension_flags` and check the `EXFLAG_INVALID` bit. OPENSSL_EXPORT const GENERAL_NAMES *X509_get0_authority_issuer(X509 *x509); -// X509_get0_authority_serial returns the authorityCertSerialNumber of |x509|'s +// X509_get0_authority_serial returns the authorityCertSerialNumber of `x509`'s // authority key identifier, if the extension and field are present. (See // RFC 5280, section 4.2.1.1.) It returns NULL if the extension is not present, // if it is present but lacks a authorityCertSerialNumber field, or if some -// extension in |x509| was invalid. +// extension in `x509` was invalid. // -// TODO(crbug.com/boringssl/381): Decoding an |X509| object will not check for +// TODO(crbug.com/boringssl/381): Decoding an `X509` object will not check for // invalid extensions. To detect the error case, call -// |X509_get_extension_flags| and check the |EXFLAG_INVALID| bit. +// `X509_get_extension_flags` and check the `EXFLAG_INVALID` bit. OPENSSL_EXPORT const ASN1_INTEGER *X509_get0_authority_serial(X509 *x509); -// X509_get0_extensions returns |x509|'s extension list, or NULL if |x509| omits +// X509_get0_extensions returns `x509`'s extension list, or NULL if `x509` omits // it. OPENSSL_EXPORT const STACK_OF(X509_EXTENSION) *X509_get0_extensions( const X509 *x509); -// X509_get_ext_count returns the number of extensions in |x|. +// X509_get_ext_count returns the number of extensions in `x`. OPENSSL_EXPORT int X509_get_ext_count(const X509 *x); -// X509_get_ext_by_NID behaves like |X509v3_get_ext_by_NID| but searches for -// extensions in |x|. +// X509_get_ext_by_NID behaves like `X509v3_get_ext_by_NID` but searches for +// extensions in `x`. OPENSSL_EXPORT int X509_get_ext_by_NID(const X509 *x, int nid, int lastpos); -// X509_get_ext_by_OBJ behaves like |X509v3_get_ext_by_OBJ| but searches for -// extensions in |x|. +// X509_get_ext_by_OBJ behaves like `X509v3_get_ext_by_OBJ` but searches for +// extensions in `x`. OPENSSL_EXPORT int X509_get_ext_by_OBJ(const X509 *x, const ASN1_OBJECT *obj, int lastpos); -// X509_get_ext_by_critical behaves like |X509v3_get_ext_by_critical| but -// searches for extensions in |x|. +// X509_get_ext_by_critical behaves like `X509v3_get_ext_by_critical` but +// searches for extensions in `x`. OPENSSL_EXPORT int X509_get_ext_by_critical(const X509 *x, int crit, int lastpos); -// X509_get_ext returns the extension in |x| at index |loc|, or NULL if |loc| is +// X509_get_ext returns the extension in `x` at index `loc`, or NULL if `loc` is // out of bounds. This function returns a non-const pointer for OpenSSL // compatibility, but callers should not mutate the result. OPENSSL_EXPORT X509_EXTENSION *X509_get_ext(const X509 *x, int loc); -// X509_get_ext_d2i behaves like |X509V3_get_d2i| but looks for the extension in -// |x509|'s extension list. +// X509_get_ext_d2i behaves like `X509V3_get_d2i` but looks for the extension in +// `x509`'s extension list. // // WARNING: This function is difficult to use correctly. See the documentation -// for |X509V3_get_d2i| for details. +// for `X509V3_get_d2i` for details. OPENSSL_EXPORT void *X509_get_ext_d2i(const X509 *x509, int nid, int *out_critical, int *out_idx); -// X509_get0_tbs_sigalg returns the signature algorithm in |x509|'s -// TBSCertificate. For the outer signature algorithm, see |X509_get0_signature|. +// X509_get0_tbs_sigalg returns the signature algorithm in `x509`'s +// TBSCertificate. For the outer signature algorithm, see `X509_get0_signature`. // // Certificates with mismatched signature algorithms will successfully parse, // but they will be rejected when verifying. OPENSSL_EXPORT const X509_ALGOR *X509_get0_tbs_sigalg(const X509 *x509); -// X509_get0_signature sets |*out_sig| and |*out_alg| to the signature and -// signature algorithm of |x509|, respectively. Either output pointer may be +// X509_get0_signature sets `*out_sig` and `*out_alg` to the signature and +// signature algorithm of `x509`, respectively. Either output pointer may be // NULL to ignore the value. // // This function outputs the outer signature algorithm. For the one in the -// TBSCertificate, see |X509_get0_tbs_sigalg|. Certificates with mismatched +// TBSCertificate, see `X509_get0_tbs_sigalg`. Certificates with mismatched // signature algorithms will successfully parse, but they will be rejected when // verifying. OPENSSL_EXPORT void X509_get0_signature(const ASN1_BIT_STRING **out_sig, const X509_ALGOR **out_alg, const X509 *x509); -// X509_get_signature_nid returns the NID corresponding to |x509|'s signature -// algorithm, or |NID_undef| if the signature algorithm does not correspond to +// X509_get_signature_nid returns the NID corresponding to `x509`'s signature +// algorithm, or `NID_undef` if the signature algorithm does not correspond to // a known NID. OPENSSL_EXPORT int X509_get_signature_nid(const X509 *x509); -// i2d_X509_tbs serializes the TBSCertificate portion of |x509|, as described in -// |i2d_SAMPLE|. +// i2d_X509_tbs serializes the TBSCertificate portion of `x509`, as described in +// `i2d_SAMPLE`. // // This function preserves the original encoding of the TBSCertificate and may -// not reflect modifications made to |x509|. It may be used to manually verify +// not reflect modifications made to `x509`. It may be used to manually verify // the signature of an existing certificate. To generate certificates, use -// |i2d_re_X509_tbs| instead. +// `i2d_re_X509_tbs` instead. OPENSSL_EXPORT int i2d_X509_tbs(const X509 *x509, uint8_t **outp); -// X509_verify checks that |x509| has a valid signature by |pkey|. It returns +// X509_verify checks that `x509` has a valid signature by `pkey`. It returns // one if the signature is valid and zero otherwise. Note this function only // checks the signature itself and does not perform a full certificate // validation. OPENSSL_EXPORT int X509_verify(const X509 *x509, EVP_PKEY *pkey); // X509_get1_email returns a newly-allocated list of NUL-terminated strings -// containing all email addresses in |x509|'s subject and all rfc822name names -// in |x509|'s subject alternative names. Email addresses which contain embedded +// containing all email addresses in `x509`'s subject and all rfc822name names +// in `x509`'s subject alternative names. Email addresses which contain embedded // NUL bytes are skipped. The results are returned in an arbitrary order. // // On error, or if there are no such email addresses, it returns NULL. When -// done, the caller must release the result with |X509_email_free|. +// done, the caller must release the result with `X509_email_free`. OPENSSL_EXPORT STACK_OF(OPENSSL_STRING) *X509_get1_email(const X509 *x509); // X509_get1_ocsp returns a newly-allocated list of NUL-terminated strings -// containing all OCSP URIs in |x509|. That is, it collects all URI -// AccessDescriptions with an accessMethod of id-ad-ocsp in |x509|'s authority +// containing all OCSP URIs in `x509`. That is, it collects all URI +// AccessDescriptions with an accessMethod of id-ad-ocsp in `x509`'s authority // information access extension. URIs which contain embedded NUL bytes are // skipped. The results are returned in an arbitrary order. // // On error, or if there are no such URIs, it returns NULL. When done, the -// caller must release the result with |X509_email_free|. +// caller must release the result with `X509_email_free`. OPENSSL_EXPORT STACK_OF(OPENSSL_STRING) *X509_get1_ocsp(const X509 *x509); -// X509_email_free releases memory associated with |sk|, including |sk| itself. -// Each |OPENSSL_STRING| in |sk| must be a NUL-terminated string allocated with -// |OPENSSL_malloc|. If |sk| is NULL, no action is taken. +// X509_email_free releases memory associated with `sk`, including `sk` itself. +// Each `OPENSSL_STRING` in `sk` must be a NUL-terminated string allocated with +// `OPENSSL_malloc`. If `sk` is NULL, no action is taken. OPENSSL_EXPORT void X509_email_free(STACK_OF(OPENSSL_STRING) *sk); -// X509_cmp compares |a| and |b| and returns zero if they are equal, a negative -// number if |b| sorts after |a| and a negative number if |a| sorts after |b|. +// X509_cmp compares `a` and `b` and returns zero if they are equal, a negative +// number if `b` sorts after `a` and a negative number if `a` sorts after `b`. // The sort order implemented by this function is arbitrary and does not // reflect properties of the certificate such as expiry. Applications should not // rely on the order itself. // // TODO(https://crbug.com/boringssl/355): This function works by comparing a -// cached hash of the encoded certificate. If |a| or |b| could not be +// cached hash of the encoded certificate. If `a` or `b` could not be // serialized, the current behavior is to compare all unencodable certificates -// as equal. This function should only be used with |X509| objects that were +// as equal. This function should only be used with `X509` objects that were // parsed from bytes and never mutated. OPENSSL_EXPORT int X509_cmp(const X509 *a, const X509 *b); // Issuing certificates. // -// An |X509| object may also represent an incomplete certificate. Callers may -// construct empty |X509| objects, fill in fields individually, and finally sign +// An `X509` object may also represent an incomplete certificate. Callers may +// construct empty `X509` objects, fill in fields individually, and finally sign // the result. The following functions may be used for this purpose. -// X509_new returns a newly-allocated, empty |X509| object, or NULL on error. +// X509_new returns a newly-allocated, empty `X509` object, or NULL on error. // This produces an incomplete certificate which may be filled in to issue a new // certificate. OPENSSL_EXPORT X509 *X509_new(void); -// X509_set_version sets |x509|'s version to |version|, which should be one of -// the |X509V_VERSION_*| constants. It returns one on success and zero on error. +// X509_set_version sets `x509`'s version to `version`, which should be one of +// the `X509V_VERSION_*` constants. It returns one on success and zero on error. // -// If unsure, use |X509_VERSION_3|. +// If unsure, use `X509_VERSION_3`. OPENSSL_EXPORT int X509_set_version(X509 *x509, long version); -// X509_set_serialNumber sets |x509|'s serial number to |serial|. It returns one +// X509_set_serialNumber sets `x509`'s serial number to `serial`. It returns one // on success and zero on error. OPENSSL_EXPORT int X509_set_serialNumber(X509 *x509, const ASN1_INTEGER *serial); -// X509_set1_notBefore sets |x509|'s notBefore time to |tm|. It returns one on +// X509_set1_notBefore sets `x509`'s notBefore time to `tm`. It returns one on // success and zero on error. OPENSSL_EXPORT int X509_set1_notBefore(X509 *x509, const ASN1_TIME *tm); -// X509_set1_notAfter sets |x509|'s notAfter time to |tm|. it returns one on +// X509_set1_notAfter sets `x509`'s notAfter time to `tm`. it returns one on // success and zero on error. OPENSSL_EXPORT int X509_set1_notAfter(X509 *x509, const ASN1_TIME *tm); -// X509_getm_notBefore returns a mutable pointer to |x509|'s notBefore time. +// X509_getm_notBefore returns a mutable pointer to `x509`'s notBefore time. OPENSSL_EXPORT ASN1_TIME *X509_getm_notBefore(X509 *x509); -// X509_getm_notAfter returns a mutable pointer to |x509|'s notAfter time. +// X509_getm_notAfter returns a mutable pointer to `x509`'s notAfter time. OPENSSL_EXPORT ASN1_TIME *X509_getm_notAfter(X509 *x); -// X509_set_issuer_name sets |x509|'s issuer to a copy of |name|. It returns one +// X509_set_issuer_name sets `x509`'s issuer to a copy of `name`. It returns one // on success and zero on error. OPENSSL_EXPORT int X509_set_issuer_name(X509 *x509, const X509_NAME *name); -// X509_set_subject_name sets |x509|'s subject to a copy of |name|. It returns +// X509_set_subject_name sets `x509`'s subject to a copy of `name`. It returns // one on success and zero on error. OPENSSL_EXPORT int X509_set_subject_name(X509 *x509, const X509_NAME *name); -// X509_set_pubkey sets |x509|'s public key to |pkey|. It returns one on success -// and zero on error. This function does not take ownership of |pkey| and +// X509_set_pubkey sets `x509`'s public key to `pkey`. It returns one on success +// and zero on error. This function does not take ownership of `pkey` and // internally copies and updates reference counts as needed. OPENSSL_EXPORT int X509_set_pubkey(X509 *x509, EVP_PKEY *pkey); -// X509_delete_ext removes the extension in |x| at index |loc| and returns the -// removed extension, or NULL if |loc| was out of bounds. If non-NULL, the -// caller must release the result with |X509_EXTENSION_free|. +// X509_delete_ext removes the extension in `x` at index `loc` and returns the +// removed extension, or NULL if `loc` was out of bounds. If non-NULL, the +// caller must release the result with `X509_EXTENSION_free`. OPENSSL_EXPORT X509_EXTENSION *X509_delete_ext(X509 *x, int loc); -// X509_add_ext adds a copy of |ex| to |x|. It returns one on success and zero -// on failure. The caller retains ownership of |ex| and can release it -// independently of |x|. +// X509_add_ext adds a copy of `ex` to `x`. It returns one on success and zero +// on failure. The caller retains ownership of `ex` and can release it +// independently of `x`. // -// The new extension is inserted at index |loc|, shifting extensions to the -// right. If |loc| is -1 or out of bounds, the new extension is appended to the +// The new extension is inserted at index `loc`, shifting extensions to the +// right. If `loc` is -1 or out of bounds, the new extension is appended to the // list. OPENSSL_EXPORT int X509_add_ext(X509 *x, const X509_EXTENSION *ex, int loc); -// X509_add1_ext_i2d behaves like |X509V3_add1_i2d| but adds the extension to -// |x|'s extension list. +// X509_add1_ext_i2d behaves like `X509V3_add1_i2d` but adds the extension to +// `x`'s extension list. // // WARNING: This function may return zero or -1 on error. The caller must also -// ensure |value|'s type matches |nid|. See the documentation for -// |X509V3_add1_i2d| for details. +// ensure `value`'s type matches `nid`. See the documentation for +// `X509V3_add1_i2d` for details. OPENSSL_EXPORT int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit, unsigned long flags); -// X509_sign signs |x509| with |pkey| and replaces the signature algorithm and +// X509_sign signs `x509` with `pkey` and replaces the signature algorithm and // signature fields. It returns the length of the signature on success and zero -// on error. This function uses digest algorithm |md|, or |pkey|'s default if -// NULL. Other signing parameters use |pkey|'s defaults. To customize them, use -// |X509_sign_ctx|. +// on error. This function uses digest algorithm `md`, or `pkey`'s default if +// NULL. Other signing parameters use `pkey`'s defaults. To customize them, use +// `X509_sign_ctx`. OPENSSL_EXPORT int X509_sign(X509 *x509, EVP_PKEY *pkey, const EVP_MD *md); -// X509_sign_ctx signs |x509| with |ctx| and replaces the signature algorithm +// X509_sign_ctx signs `x509` with `ctx` and replaces the signature algorithm // and signature fields. It returns the length of the signature on success and -// zero on error. The signature algorithm and parameters come from |ctx|, which -// must have been initialized with |EVP_DigestSignInit|. The caller should -// configure the corresponding |EVP_PKEY_CTX| before calling this function. +// zero on error. The signature algorithm and parameters come from `ctx`, which +// must have been initialized with `EVP_DigestSignInit`. The caller should +// configure the corresponding `EVP_PKEY_CTX` before calling this function. // -// On success or failure, this function mutates |ctx| and resets it to the empty +// On success or failure, this function mutates `ctx` and resets it to the empty // state. Caller should not rely on its contents after the function returns. OPENSSL_EXPORT int X509_sign_ctx(X509 *x509, EVP_MD_CTX *ctx); -// i2d_re_X509_tbs serializes the TBSCertificate portion of |x509|, as described -// in |i2d_SAMPLE|. +// i2d_re_X509_tbs serializes the TBSCertificate portion of `x509`, as described +// in `i2d_SAMPLE`. // -// This function re-encodes the TBSCertificate and may not reflect |x509|'s +// This function re-encodes the TBSCertificate and may not reflect `x509`'s // original encoding. It may be used to manually generate a signature for a new -// certificate. To verify certificates, use |i2d_X509_tbs| instead. +// certificate. To verify certificates, use `i2d_X509_tbs` instead. // -// Unlike |i2d_X509_tbs|, this function is not |const| and thus may not be to -// use concurrently with other functions that access |x509|. It mutates |x509| +// Unlike `i2d_X509_tbs`, this function is not `const` and thus may not be to +// use concurrently with other functions that access `x509`. It mutates `x509` // by dropping the cached encoding. This function is intended to be used during -// certificate construction, where |x509| is still single-threaded and being +// certificate construction, where `x509` is still single-threaded and being // mutated. OPENSSL_EXPORT int i2d_re_X509_tbs(X509 *x509, uint8_t **outp); -// X509_set1_signature_algo sets |x509|'s signature algorithm to |algo| and +// X509_set1_signature_algo sets `x509`'s signature algorithm to `algo` and // returns one on success or zero on error. It updates both the signature field // of the TBSCertificate structure, and the signatureAlgorithm field of the // Certificate. OPENSSL_EXPORT int X509_set1_signature_algo(X509 *x509, const X509_ALGOR *algo); -// X509_set1_signature_value sets |x509|'s signature to a copy of the |sig_len| -// bytes pointed by |sig|. It returns one on success and zero on error. +// X509_set1_signature_value sets `x509`'s signature to a copy of the `sig_len` +// bytes pointed by `sig`. It returns one on success and zero on error. // // Due to a specification error, X.509 certificates store signatures in ASN.1 // BIT STRINGs, but signature algorithms return byte strings rather than bit @@ -564,29 +564,29 @@ // Auxiliary certificate properties. // -// |X509| objects optionally maintain auxiliary properties. These are not part +// `X509` objects optionally maintain auxiliary properties. These are not part // of the certificates themselves, and thus are not covered by signatures or // preserved by the standard serialization. They are used as inputs or outputs // to other functions in this library. -// i2d_X509_AUX marshals |x509| as a DER-encoded X.509 Certificate (RFC 5280), +// i2d_X509_AUX marshals `x509` as a DER-encoded X.509 Certificate (RFC 5280), // followed optionally by a separate, OpenSSL-specific structure with auxiliary -// properties. It behaves as described in |i2d_SAMPLE|. +// properties. It behaves as described in `i2d_SAMPLE`. // // Unlike similarly-named functions, this function does not output a single // ASN.1 element. Directly embedding the output in a larger ASN.1 structure will // not behave correctly. OPENSSL_EXPORT int i2d_X509_AUX(const X509 *x509, uint8_t **outp); -// d2i_X509_AUX parses up to |length| bytes from |*inp| as a DER-encoded X.509 +// d2i_X509_AUX parses up to `length` bytes from `*inp` as a DER-encoded X.509 // Certificate (RFC 5280), followed optionally by a separate, OpenSSL-specific -// structure with auxiliary properties. It behaves as described in |d2i_SAMPLE|. +// structure with auxiliary properties. It behaves as described in `d2i_SAMPLE`. // // WARNING: Passing untrusted input to this function allows an attacker to // control auxiliary properties. This can allow unexpected influence over the // application if the certificate is used in a context that reads auxiliary // properties. This includes PKCS#12 serialization, trusted certificates in -// |X509_STORE|, and callers of |X509_alias_get0| or |X509_keyid_get0|. +// `X509_STORE`, and callers of `X509_alias_get0` or `X509_keyid_get0`. // // Unlike similarly-named functions, this function does not parse a single // ASN.1 element. Trying to parse data directly embedded in a larger ASN.1 @@ -594,82 +594,82 @@ OPENSSL_EXPORT X509 *d2i_X509_AUX(X509 **x509, const uint8_t **inp, long length); -// X509_alias_set1 sets |x509|'s alias to |len| bytes from |name|. If |name| is +// X509_alias_set1 sets `x509`'s alias to `len` bytes from `name`. If `name` is // NULL, the alias is cleared instead. Aliases are not part of the certificate -// itself and will not be serialized by |i2d_X509|. If |x509| is serialized in +// itself and will not be serialized by `i2d_X509`. If `x509` is serialized in // a PKCS#12 structure, the friendlyName attribute (RFC 2985) will contain this // alias. OPENSSL_EXPORT int X509_alias_set1(X509 *x509, const uint8_t *name, ossl_ssize_t len); -// X509_keyid_set1 sets |x509|'s key ID to |len| bytes from |id|. If |id| is +// X509_keyid_set1 sets `x509`'s key ID to `len` bytes from `id`. If `id` is // NULL, the key ID is cleared instead. Key IDs are not part of the certificate -// itself and will not be serialized by |i2d_X509|. +// itself and will not be serialized by `i2d_X509`. OPENSSL_EXPORT int X509_keyid_set1(X509 *x509, const uint8_t *id, ossl_ssize_t len); -// X509_alias_get0 looks up |x509|'s alias. If found, it sets |*out_len| to the +// X509_alias_get0 looks up `x509`'s alias. If found, it sets `*out_len` to the // alias's length and returns a pointer to a buffer containing the contents. If // not found, it outputs the empty string by returning NULL and setting -// |*out_len| to zero. +// `*out_len` to zero. // -// If |x509| was parsed from a PKCS#12 structure (see -// |PKCS12_get_key_and_certs|), the alias will reflect the friendlyName +// If `x509` was parsed from a PKCS#12 structure (see +// `PKCS12_get_key_and_certs`), the alias will reflect the friendlyName // attribute (RFC 2985). // -// WARNING: In OpenSSL, this function did not set |*out_len| when the alias was +// WARNING: In OpenSSL, this function did not set `*out_len` when the alias was // missing. Callers that target both OpenSSL and BoringSSL should set the value // to zero before calling this function. OPENSSL_EXPORT const uint8_t *X509_alias_get0(const X509 *x509, int *out_len); -// X509_keyid_get0 looks up |x509|'s key ID. If found, it sets |*out_len| to the +// X509_keyid_get0 looks up `x509`'s key ID. If found, it sets `*out_len` to the // key ID's length and returns a pointer to a buffer containing the contents. If // not found, it outputs the empty string by returning NULL and setting -// |*out_len| to zero. +// `*out_len` to zero. // -// WARNING: In OpenSSL, this function did not set |*out_len| when the alias was +// WARNING: In OpenSSL, this function did not set `*out_len` when the alias was // missing. Callers that target both OpenSSL and BoringSSL should set the value // to zero before calling this function. OPENSSL_EXPORT const uint8_t *X509_keyid_get0(const X509 *x509, int *out_len); -// X509_add1_trust_object configures |x509| as a valid trust anchor for |obj|. -// It returns one on success and zero on error. |obj| should be a certificate -// usage OID associated with an |X509_TRUST_*| constant. +// X509_add1_trust_object configures `x509` as a valid trust anchor for `obj`. +// It returns one on success and zero on error. `obj` should be a certificate +// usage OID associated with an `X509_TRUST_*` constant. // -// See |X509_VERIFY_PARAM_set_trust| for details on how this value is evaluated. -// Note this only takes effect if |x509| was configured as a trusted certificate -// via |X509_STORE|. +// See `X509_VERIFY_PARAM_set_trust` for details on how this value is evaluated. +// Note this only takes effect if `x509` was configured as a trusted certificate +// via `X509_STORE`. OPENSSL_EXPORT int X509_add1_trust_object(X509 *x509, const ASN1_OBJECT *obj); -// X509_add1_reject_object configures |x509| as distrusted for |obj|. It returns -// one on success and zero on error. |obj| should be a certificate usage OID -// associated with an |X509_TRUST_*| constant. +// X509_add1_reject_object configures `x509` as distrusted for `obj`. It returns +// one on success and zero on error. `obj` should be a certificate usage OID +// associated with an `X509_TRUST_*` constant. // -// See |X509_VERIFY_PARAM_set_trust| for details on how this value is evaluated. -// Note this only takes effect if |x509| was configured as a trusted certificate -// via |X509_STORE|. +// See `X509_VERIFY_PARAM_set_trust` for details on how this value is evaluated. +// Note this only takes effect if `x509` was configured as a trusted certificate +// via `X509_STORE`. OPENSSL_EXPORT int X509_add1_reject_object(X509 *x509, const ASN1_OBJECT *obj); -// X509_trust_clear clears the list of OIDs for which |x509| is trusted. See -// also |X509_add1_trust_object|. +// X509_trust_clear clears the list of OIDs for which `x509` is trusted. See +// also `X509_add1_trust_object`. OPENSSL_EXPORT void X509_trust_clear(X509 *x509); -// X509_reject_clear clears the list of OIDs for which |x509| is distrusted. See -// also |X509_add1_reject_object|. +// X509_reject_clear clears the list of OIDs for which `x509` is distrusted. See +// also `X509_add1_reject_object`. OPENSSL_EXPORT void X509_reject_clear(X509 *x509); // Certificate revocation lists. // -// An |X509_CRL| object represents an X.509 certificate revocation list (CRL), +// An `X509_CRL` object represents an X.509 certificate revocation list (CRL), // defined in RFC 5280. A CRL is a signed list of certificates, the // revokedCertificates field, which are no longer considered valid. Each entry -// of this list is represented with an |X509_REVOKED| object, documented in the +// of this list is represented with an `X509_REVOKED` object, documented in the // "CRL entries" section below. // -// Although an |X509_CRL| is a mutable object, mutating an |X509_CRL| or its -// |X509_REVOKED|s can give incorrect results. Callers typically obtain -// |X509_CRL|s by parsing some input with |d2i_X509_CRL|, etc. Such objects +// Although an `X509_CRL` is a mutable object, mutating an `X509_CRL` or its +// `X509_REVOKED`s can give incorrect results. Callers typically obtain +// `X509_CRL`s by parsing some input with `d2i_X509_CRL`, etc. Such objects // carry information such as the serialized TBSCertList and decoded extensions, // which will become inconsistent when mutated. // @@ -679,128 +679,128 @@ DEFINE_STACK_OF(X509_CRL) DEFINE_STACK_OF(X509_REVOKED) -// X509_CRL_up_ref adds one to the reference count of |crl| and returns one. +// X509_CRL_up_ref adds one to the reference count of `crl` and returns one. OPENSSL_EXPORT int X509_CRL_up_ref(X509_CRL *crl); -// X509_CRL_dup returns a newly-allocated copy of |crl|, or NULL on error. This -// function works by serializing the structure, so if |crl| is incomplete, it +// X509_CRL_dup returns a newly-allocated copy of `crl`, or NULL on error. This +// function works by serializing the structure, so if `crl` is incomplete, it // may fail. OPENSSL_EXPORT X509_CRL *X509_CRL_dup(const X509_CRL *crl); -// X509_CRL_free decrements |crl|'s reference count and, if zero, releases -// memory associated with |crl|. +// X509_CRL_free decrements `crl`'s reference count and, if zero, releases +// memory associated with `crl`. OPENSSL_EXPORT void X509_CRL_free(X509_CRL *crl); -// d2i_X509_CRL parses up to |len| bytes from |*inp| as a DER-encoded X.509 -// CertificateList (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_X509_CRL parses up to `len` bytes from `*inp` as a DER-encoded X.509 +// CertificateList (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509_CRL *d2i_X509_CRL(X509_CRL **out, const uint8_t **inp, long len); -// i2d_X509_CRL marshals |crl| as a X.509 CertificateList (RFC 5280), as -// described in |i2d_SAMPLE|. +// i2d_X509_CRL marshals `crl` as a X.509 CertificateList (RFC 5280), as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509_CRL(const X509_CRL *crl, uint8_t **outp); -// X509_CRL_match compares |a| and |b| and returns zero if they are equal, a -// negative number if |b| sorts after |a| and a negative number if |a| sorts -// after |b|. The sort order implemented by this function is arbitrary and does +// X509_CRL_match compares `a` and `b` and returns zero if they are equal, a +// negative number if `b` sorts after `a` and a negative number if `a` sorts +// after `b`. The sort order implemented by this function is arbitrary and does // not reflect properties of the CRL such as expiry. Applications should not // rely on the order itself. // // TODO(https://crbug.com/boringssl/355): This function works by comparing a // cached hash of the encoded CRL. This cached hash is computed when the CRL is // parsed, but not when mutating or issuing CRLs. This function should only be -// used with |X509_CRL| objects that were parsed from bytes and never mutated. +// used with `X509_CRL` objects that were parsed from bytes and never mutated. OPENSSL_EXPORT int X509_CRL_match(const X509_CRL *a, const X509_CRL *b); #define X509_CRL_VERSION_1 0 #define X509_CRL_VERSION_2 1 -// X509_CRL_get_version returns the numerical value of |crl|'s version, which -// will be one of the |X509_CRL_VERSION_*| constants. +// X509_CRL_get_version returns the numerical value of `crl`'s version, which +// will be one of the `X509_CRL_VERSION_*` constants. OPENSSL_EXPORT long X509_CRL_get_version(const X509_CRL *crl); -// X509_CRL_get0_lastUpdate returns |crl|'s thisUpdate time. The OpenSSL API +// X509_CRL_get0_lastUpdate returns `crl`'s thisUpdate time. The OpenSSL API // refers to this field as lastUpdate. OPENSSL_EXPORT const ASN1_TIME *X509_CRL_get0_lastUpdate(const X509_CRL *crl); -// X509_CRL_get0_nextUpdate returns |crl|'s nextUpdate time, or NULL if |crl| +// X509_CRL_get0_nextUpdate returns `crl`'s nextUpdate time, or NULL if `crl` // has none. OPENSSL_EXPORT const ASN1_TIME *X509_CRL_get0_nextUpdate(const X509_CRL *crl); -// X509_CRL_get_issuer returns |crl|'s issuer name. Note this function is not +// X509_CRL_get_issuer returns `crl`'s issuer name. Note this function is not // const-correct for legacy reasons. OPENSSL_EXPORT X509_NAME *X509_CRL_get_issuer(const X509_CRL *crl); -// X509_CRL_get0_by_serial finds the entry in |crl| whose serial number is -// |serial|. If found, it sets |*out| to the entry and returns one. If not +// X509_CRL_get0_by_serial finds the entry in `crl` whose serial number is +// `serial`. If found, it sets `*out` to the entry and returns one. If not // found, it returns zero. // -// On success, |*out| continues to be owned by |crl|. It is an error to free or -// otherwise modify |*out|. +// On success, `*out` continues to be owned by `crl`. It is an error to free or +// otherwise modify `*out`. // -// TODO(crbug.com/42290473): Ideally |crl| would be const. It is broadly -// thread-safe, but changes the order of entries in |crl|. It cannot be called -// concurrently with |i2d_X509_CRL|. +// TODO(crbug.com/42290473): Ideally `crl` would be const. It is broadly +// thread-safe, but changes the order of entries in `crl`. It cannot be called +// concurrently with `i2d_X509_CRL`. OPENSSL_EXPORT int X509_CRL_get0_by_serial(X509_CRL *crl, X509_REVOKED **out, const ASN1_INTEGER *serial); -// X509_CRL_get0_by_cert behaves like |X509_CRL_get0_by_serial|, except it looks -// for the entry that matches |x509|. +// X509_CRL_get0_by_cert behaves like `X509_CRL_get0_by_serial`, except it looks +// for the entry that matches `x509`. // -// TODO(crbug.com/42290473): Ideally |crl| would be const. It is broadly -// thread-safe, but changes the order of entries in |crl|. It cannot be called -// concurrently with |i2d_X509_CRL|. +// TODO(crbug.com/42290473): Ideally `crl` would be const. It is broadly +// thread-safe, but changes the order of entries in `crl`. It cannot be called +// concurrently with `i2d_X509_CRL`. OPENSSL_EXPORT int X509_CRL_get0_by_cert(X509_CRL *crl, X509_REVOKED **out, const X509 *x509); -// X509_CRL_get_REVOKED returns the list of revoked certificates in |crl|, or -// NULL if |crl| omits it. +// X509_CRL_get_REVOKED returns the list of revoked certificates in `crl`, or +// NULL if `crl` omits it. // // TODO(davidben): This function was originally a macro, without clear const // semantics. It should take a const input and give const output, but the latter // would break existing callers. For now, we match upstream. OPENSSL_EXPORT STACK_OF(X509_REVOKED) *X509_CRL_get_REVOKED(X509_CRL *crl); -// X509_CRL_get0_extensions returns |crl|'s extension list, or NULL if |crl| +// X509_CRL_get0_extensions returns `crl`'s extension list, or NULL if `crl` // omits it. A CRL can have extensions on individual entries, which is -// |X509_REVOKED_get0_extensions|, or on the overall CRL, which is this +// `X509_REVOKED_get0_extensions`, or on the overall CRL, which is this // function. OPENSSL_EXPORT const STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions( const X509_CRL *crl); -// X509_CRL_get_ext_count returns the number of extensions in |x|. +// X509_CRL_get_ext_count returns the number of extensions in `x`. OPENSSL_EXPORT int X509_CRL_get_ext_count(const X509_CRL *x); -// X509_CRL_get_ext_by_NID behaves like |X509v3_get_ext_by_NID| but searches for -// extensions in |x|. +// X509_CRL_get_ext_by_NID behaves like `X509v3_get_ext_by_NID` but searches for +// extensions in `x`. OPENSSL_EXPORT int X509_CRL_get_ext_by_NID(const X509_CRL *x, int nid, int lastpos); -// X509_CRL_get_ext_by_OBJ behaves like |X509v3_get_ext_by_OBJ| but searches for -// extensions in |x|. +// X509_CRL_get_ext_by_OBJ behaves like `X509v3_get_ext_by_OBJ` but searches for +// extensions in `x`. OPENSSL_EXPORT int X509_CRL_get_ext_by_OBJ(const X509_CRL *x, const ASN1_OBJECT *obj, int lastpos); -// X509_CRL_get_ext_by_critical behaves like |X509v3_get_ext_by_critical| but -// searches for extensions in |x|. +// X509_CRL_get_ext_by_critical behaves like `X509v3_get_ext_by_critical` but +// searches for extensions in `x`. OPENSSL_EXPORT int X509_CRL_get_ext_by_critical(const X509_CRL *x, int crit, int lastpos); -// X509_CRL_get_ext returns the extension in |x| at index |loc|, or NULL if -// |loc| is out of bounds. This function returns a non-const pointer for OpenSSL +// X509_CRL_get_ext returns the extension in `x` at index `loc`, or NULL if +// `loc` is out of bounds. This function returns a non-const pointer for OpenSSL // compatibility, but callers should not mutate the result. OPENSSL_EXPORT X509_EXTENSION *X509_CRL_get_ext(const X509_CRL *x, int loc); -// X509_CRL_get_ext_d2i behaves like |X509V3_get_d2i| but looks for the -// extension in |crl|'s extension list. +// X509_CRL_get_ext_d2i behaves like `X509V3_get_d2i` but looks for the +// extension in `crl`'s extension list. // // WARNING: This function is difficult to use correctly. See the documentation -// for |X509V3_get_d2i| for details. +// for `X509V3_get_d2i` for details. OPENSSL_EXPORT void *X509_CRL_get_ext_d2i(const X509_CRL *crl, int nid, int *out_critical, int *out_idx); -// X509_CRL_get0_signature sets |*out_sig| and |*out_alg| to the signature and -// signature algorithm of |crl|, respectively. Either output pointer may be NULL +// X509_CRL_get0_signature sets `*out_sig` and `*out_alg` to the signature and +// signature algorithm of `crl`, respectively. Either output pointer may be NULL // to ignore the value. // // This function outputs the outer signature algorithm, not the one in the @@ -810,124 +810,124 @@ const ASN1_BIT_STRING **out_sig, const X509_ALGOR **out_alg); -// X509_CRL_get_signature_nid returns the NID corresponding to |crl|'s signature -// algorithm, or |NID_undef| if the signature algorithm does not correspond to +// X509_CRL_get_signature_nid returns the NID corresponding to `crl`'s signature +// algorithm, or `NID_undef` if the signature algorithm does not correspond to // a known NID. OPENSSL_EXPORT int X509_CRL_get_signature_nid(const X509_CRL *crl); -// i2d_X509_CRL_tbs serializes the TBSCertList portion of |crl|, as described in -// |i2d_SAMPLE|. +// i2d_X509_CRL_tbs serializes the TBSCertList portion of `crl`, as described in +// `i2d_SAMPLE`. // // This function preserves the original encoding of the TBSCertList and may not -// reflect modifications made to |crl|. It may be used to manually verify the -// signature of an existing CRL. To generate CRLs, use |i2d_re_X509_CRL_tbs| +// reflect modifications made to `crl`. It may be used to manually verify the +// signature of an existing CRL. To generate CRLs, use `i2d_re_X509_CRL_tbs` // instead. OPENSSL_EXPORT int i2d_X509_CRL_tbs(const X509_CRL *crl, unsigned char **outp); -// X509_CRL_verify checks that |crl| has a valid signature by |pkey|. It returns +// X509_CRL_verify checks that `crl` has a valid signature by `pkey`. It returns // one if the signature is valid and zero otherwise. OPENSSL_EXPORT int X509_CRL_verify(const X509_CRL *crl, EVP_PKEY *pkey); // Issuing certificate revocation lists. // -// An |X509_CRL| object may also represent an incomplete CRL. Callers may -// construct empty |X509_CRL| objects, fill in fields individually, and finally +// An `X509_CRL` object may also represent an incomplete CRL. Callers may +// construct empty `X509_CRL` objects, fill in fields individually, and finally // sign the result. The following functions may be used for this purpose. -// X509_CRL_new returns a newly-allocated, empty |X509_CRL| object, or NULL on +// X509_CRL_new returns a newly-allocated, empty `X509_CRL` object, or NULL on // error. This object may be filled in and then signed to construct a CRL. OPENSSL_EXPORT X509_CRL *X509_CRL_new(void); -// X509_CRL_set_version sets |crl|'s version to |version|, which should be one -// of the |X509_CRL_VERSION_*| constants. It returns one on success and zero on +// X509_CRL_set_version sets `crl`'s version to `version`, which should be one +// of the `X509_CRL_VERSION_*` constants. It returns one on success and zero on // error. // -// If unsure, use |X509_CRL_VERSION_2|. Note that, unlike certificates, CRL -// versions are only defined up to v2. Callers should not use |X509_VERSION_3|. +// If unsure, use `X509_CRL_VERSION_2`. Note that, unlike certificates, CRL +// versions are only defined up to v2. Callers should not use `X509_VERSION_3`. OPENSSL_EXPORT int X509_CRL_set_version(X509_CRL *crl, long version); -// X509_CRL_set_issuer_name sets |crl|'s issuer to a copy of |name|. It returns +// X509_CRL_set_issuer_name sets `crl`'s issuer to a copy of `name`. It returns // one on success and zero on error. OPENSSL_EXPORT int X509_CRL_set_issuer_name(X509_CRL *crl, const X509_NAME *name); -// X509_CRL_set1_lastUpdate sets |crl|'s thisUpdate time to |tm|. It returns one +// X509_CRL_set1_lastUpdate sets `crl`'s thisUpdate time to `tm`. It returns one // on success and zero on error. The OpenSSL API refers to this field as // lastUpdate. OPENSSL_EXPORT int X509_CRL_set1_lastUpdate(X509_CRL *crl, const ASN1_TIME *tm); -// X509_CRL_set1_nextUpdate sets |crl|'s nextUpdate time to |tm|. It returns one +// X509_CRL_set1_nextUpdate sets `crl`'s nextUpdate time to `tm`. It returns one // on success and zero on error. OPENSSL_EXPORT int X509_CRL_set1_nextUpdate(X509_CRL *crl, const ASN1_TIME *tm); -// X509_CRL_add0_revoked adds |rev| to |crl|. On success, it takes ownership of -// |rev| and returns one. On error, it returns zero. If this function fails, the -// caller retains ownership of |rev| and must release it when done. +// X509_CRL_add0_revoked adds `rev` to `crl`. On success, it takes ownership of +// `rev` and returns one. On error, it returns zero. If this function fails, the +// caller retains ownership of `rev` and must release it when done. OPENSSL_EXPORT int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); -// X509_CRL_sort sorts the entries in |crl| by serial number. It returns one on +// X509_CRL_sort sorts the entries in `crl` by serial number. It returns one on // success and zero on error. OPENSSL_EXPORT int X509_CRL_sort(X509_CRL *crl); -// X509_CRL_delete_ext removes the extension in |x| at index |loc| and returns -// the removed extension, or NULL if |loc| was out of bounds. If non-NULL, the -// caller must release the result with |X509_EXTENSION_free|. +// X509_CRL_delete_ext removes the extension in `x` at index `loc` and returns +// the removed extension, or NULL if `loc` was out of bounds. If non-NULL, the +// caller must release the result with `X509_EXTENSION_free`. OPENSSL_EXPORT X509_EXTENSION *X509_CRL_delete_ext(X509_CRL *x, int loc); -// X509_CRL_add_ext adds a copy of |ex| to |x|. It returns one on success and -// zero on failure. The caller retains ownership of |ex| and can release it -// independently of |x|. +// X509_CRL_add_ext adds a copy of `ex` to `x`. It returns one on success and +// zero on failure. The caller retains ownership of `ex` and can release it +// independently of `x`. // -// The new extension is inserted at index |loc|, shifting extensions to the -// right. If |loc| is -1 or out of bounds, the new extension is appended to the +// The new extension is inserted at index `loc`, shifting extensions to the +// right. If `loc` is -1 or out of bounds, the new extension is appended to the // list. OPENSSL_EXPORT int X509_CRL_add_ext(X509_CRL *x, const X509_EXTENSION *ex, int loc); -// X509_CRL_add1_ext_i2d behaves like |X509V3_add1_i2d| but adds the extension -// to |x|'s extension list. +// X509_CRL_add1_ext_i2d behaves like `X509V3_add1_i2d` but adds the extension +// to `x`'s extension list. // // WARNING: This function may return zero or -1 on error. The caller must also -// ensure |value|'s type matches |nid|. See the documentation for -// |X509V3_add1_i2d| for details. +// ensure `value`'s type matches `nid`. See the documentation for +// `X509V3_add1_i2d` for details. OPENSSL_EXPORT int X509_CRL_add1_ext_i2d(X509_CRL *x, int nid, void *value, int crit, unsigned long flags); -// X509_CRL_sign signs |crl| with |pkey| and replaces the signature algorithm +// X509_CRL_sign signs `crl` with `pkey` and replaces the signature algorithm // and signature fields. It returns the length of the signature on success and -// zero on error. This function uses digest algorithm |md|, or |pkey|'s default -// if NULL. Other signing parameters use |pkey|'s defaults. To customize them, -// use |X509_CRL_sign_ctx|. +// zero on error. This function uses digest algorithm `md`, or `pkey`'s default +// if NULL. Other signing parameters use `pkey`'s defaults. To customize them, +// use `X509_CRL_sign_ctx`. OPENSSL_EXPORT int X509_CRL_sign(X509_CRL *crl, EVP_PKEY *pkey, const EVP_MD *md); -// X509_CRL_sign_ctx signs |crl| with |ctx| and replaces the signature algorithm +// X509_CRL_sign_ctx signs `crl` with `ctx` and replaces the signature algorithm // and signature fields. It returns the length of the signature on success and -// zero on error. The signature algorithm and parameters come from |ctx|, which -// must have been initialized with |EVP_DigestSignInit|. The caller should -// configure the corresponding |EVP_PKEY_CTX| before calling this function. +// zero on error. The signature algorithm and parameters come from `ctx`, which +// must have been initialized with `EVP_DigestSignInit`. The caller should +// configure the corresponding `EVP_PKEY_CTX` before calling this function. // -// On success or failure, this function mutates |ctx| and resets it to the empty +// On success or failure, this function mutates `ctx` and resets it to the empty // state. Caller should not rely on its contents after the function returns. OPENSSL_EXPORT int X509_CRL_sign_ctx(X509_CRL *crl, EVP_MD_CTX *ctx); -// i2d_re_X509_CRL_tbs serializes the TBSCertList portion of |crl|, as described -// in |i2d_SAMPLE|. +// i2d_re_X509_CRL_tbs serializes the TBSCertList portion of `crl`, as described +// in `i2d_SAMPLE`. // -// This function re-encodes the TBSCertList and may not reflect |crl|'s original +// This function re-encodes the TBSCertList and may not reflect `crl`'s original // encoding. It may be used to manually generate a signature for a new CRL. To -// verify CRLs, use |i2d_X509_CRL_tbs| instead. +// verify CRLs, use `i2d_X509_CRL_tbs` instead. OPENSSL_EXPORT int i2d_re_X509_CRL_tbs(X509_CRL *crl, unsigned char **outp); -// X509_CRL_set1_signature_algo sets |crl|'s signature algorithm to |algo| and +// X509_CRL_set1_signature_algo sets `crl`'s signature algorithm to `algo` and // returns one on success or zero on error. It updates both the signature field // of the TBSCertList structure, and the signatureAlgorithm field of the CRL. OPENSSL_EXPORT int X509_CRL_set1_signature_algo(X509_CRL *crl, const X509_ALGOR *algo); -// X509_CRL_set1_signature_value sets |crl|'s signature to a copy of the -// |sig_len| bytes pointed by |sig|. It returns one on success and zero on +// X509_CRL_set1_signature_value sets `crl`'s signature to a copy of the +// `sig_len` bytes pointed by `sig`. It returns one on success and zero on // error. // // Due to a specification error, X.509 CRLs store signatures in ASN.1 BIT @@ -942,116 +942,116 @@ // CRL entries. // -// Each entry of a CRL is represented as an |X509_REVOKED| object, which +// Each entry of a CRL is represented as an `X509_REVOKED` object, which // describes a revoked certificate by serial number. // -// When an |X509_REVOKED| is obtained from an |X509_CRL| object, it is an error -// to mutate the object. Doing so may break |X509_CRL|'s and cause the library +// When an `X509_REVOKED` is obtained from an `X509_CRL` object, it is an error +// to mutate the object. Doing so may break `X509_CRL`'s and cause the library // to behave incorrectly. -// X509_REVOKED_new returns a newly-allocated, empty |X509_REVOKED| object, or +// X509_REVOKED_new returns a newly-allocated, empty `X509_REVOKED` object, or // NULL on allocation error. OPENSSL_EXPORT X509_REVOKED *X509_REVOKED_new(void); -// X509_REVOKED_free releases memory associated with |rev|. +// X509_REVOKED_free releases memory associated with `rev`. OPENSSL_EXPORT void X509_REVOKED_free(X509_REVOKED *rev); -// d2i_X509_REVOKED parses up to |len| bytes from |*inp| as a DER-encoded X.509 -// CRL entry, as described in |d2i_SAMPLE|. +// d2i_X509_REVOKED parses up to `len` bytes from `*inp` as a DER-encoded X.509 +// CRL entry, as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509_REVOKED *d2i_X509_REVOKED(X509_REVOKED **out, const uint8_t **inp, long len); -// i2d_X509_REVOKED marshals |alg| as a DER-encoded X.509 CRL entry, as -// described in |i2d_SAMPLE|. +// i2d_X509_REVOKED marshals `alg` as a DER-encoded X.509 CRL entry, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509_REVOKED(const X509_REVOKED *alg, uint8_t **outp); -// X509_REVOKED_dup returns a newly-allocated copy of |rev|, or NULL on error. -// This function works by serializing the structure, so if |rev| is incomplete, +// X509_REVOKED_dup returns a newly-allocated copy of `rev`, or NULL on error. +// This function works by serializing the structure, so if `rev` is incomplete, // it may fail. OPENSSL_EXPORT X509_REVOKED *X509_REVOKED_dup(const X509_REVOKED *rev); // X509_REVOKED_get0_serialNumber returns the serial number of the certificate -// revoked by |revoked|. +// revoked by `revoked`. OPENSSL_EXPORT const ASN1_INTEGER *X509_REVOKED_get0_serialNumber( const X509_REVOKED *revoked); -// X509_REVOKED_set_serialNumber sets |revoked|'s serial number to |serial|. It +// X509_REVOKED_set_serialNumber sets `revoked`'s serial number to `serial`. It // returns one on success or zero on error. OPENSSL_EXPORT int X509_REVOKED_set_serialNumber(X509_REVOKED *revoked, const ASN1_INTEGER *serial); // X509_REVOKED_get0_revocationDate returns the revocation time of the -// certificate revoked by |revoked|. +// certificate revoked by `revoked`. OPENSSL_EXPORT const ASN1_TIME *X509_REVOKED_get0_revocationDate( const X509_REVOKED *revoked); -// X509_REVOKED_set_revocationDate sets |revoked|'s revocation time to |tm|. It +// X509_REVOKED_set_revocationDate sets `revoked`'s revocation time to `tm`. It // returns one on success or zero on error. OPENSSL_EXPORT int X509_REVOKED_set_revocationDate(X509_REVOKED *revoked, const ASN1_TIME *tm); -// X509_REVOKED_get0_extensions returns |r|'s extensions list, or NULL if |r| +// X509_REVOKED_get0_extensions returns `r`'s extensions list, or NULL if `r` // omits it. A CRL can have extensions on individual entries, which is this -// function, or on the overall CRL, which is |X509_CRL_get0_extensions|. +// function, or on the overall CRL, which is `X509_CRL_get0_extensions`. OPENSSL_EXPORT const STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions( const X509_REVOKED *r); -// X509_REVOKED_get_ext_count returns the number of extensions in |x|. +// X509_REVOKED_get_ext_count returns the number of extensions in `x`. OPENSSL_EXPORT int X509_REVOKED_get_ext_count(const X509_REVOKED *x); -// X509_REVOKED_get_ext_by_NID behaves like |X509v3_get_ext_by_NID| but searches -// for extensions in |x|. +// X509_REVOKED_get_ext_by_NID behaves like `X509v3_get_ext_by_NID` but searches +// for extensions in `x`. OPENSSL_EXPORT int X509_REVOKED_get_ext_by_NID(const X509_REVOKED *x, int nid, int lastpos); -// X509_REVOKED_get_ext_by_OBJ behaves like |X509v3_get_ext_by_OBJ| but searches -// for extensions in |x|. +// X509_REVOKED_get_ext_by_OBJ behaves like `X509v3_get_ext_by_OBJ` but searches +// for extensions in `x`. OPENSSL_EXPORT int X509_REVOKED_get_ext_by_OBJ(const X509_REVOKED *x, const ASN1_OBJECT *obj, int lastpos); -// X509_REVOKED_get_ext_by_critical behaves like |X509v3_get_ext_by_critical| -// but searches for extensions in |x|. +// X509_REVOKED_get_ext_by_critical behaves like `X509v3_get_ext_by_critical` +// but searches for extensions in `x`. OPENSSL_EXPORT int X509_REVOKED_get_ext_by_critical(const X509_REVOKED *x, int crit, int lastpos); -// X509_REVOKED_get_ext returns the extension in |x| at index |loc|, or NULL if -// |loc| is out of bounds. This function returns a non-const pointer for OpenSSL +// X509_REVOKED_get_ext returns the extension in `x` at index `loc`, or NULL if +// `loc` is out of bounds. This function returns a non-const pointer for OpenSSL // compatibility, but callers should not mutate the result. OPENSSL_EXPORT X509_EXTENSION *X509_REVOKED_get_ext(const X509_REVOKED *x, int loc); -// X509_REVOKED_delete_ext removes the extension in |x| at index |loc| and -// returns the removed extension, or NULL if |loc| was out of bounds. If -// non-NULL, the caller must release the result with |X509_EXTENSION_free|. +// X509_REVOKED_delete_ext removes the extension in `x` at index `loc` and +// returns the removed extension, or NULL if `loc` was out of bounds. If +// non-NULL, the caller must release the result with `X509_EXTENSION_free`. OPENSSL_EXPORT X509_EXTENSION *X509_REVOKED_delete_ext(X509_REVOKED *x, int loc); -// X509_REVOKED_add_ext adds a copy of |ex| to |x|. It returns one on success -// and zero on failure. The caller retains ownership of |ex| and can release it -// independently of |x|. +// X509_REVOKED_add_ext adds a copy of `ex` to `x`. It returns one on success +// and zero on failure. The caller retains ownership of `ex` and can release it +// independently of `x`. // -// The new extension is inserted at index |loc|, shifting extensions to the -// right. If |loc| is -1 or out of bounds, the new extension is appended to the +// The new extension is inserted at index `loc`, shifting extensions to the +// right. If `loc` is -1 or out of bounds, the new extension is appended to the // list. OPENSSL_EXPORT int X509_REVOKED_add_ext(X509_REVOKED *x, const X509_EXTENSION *ex, int loc); -// X509_REVOKED_get_ext_d2i behaves like |X509V3_get_d2i| but looks for the -// extension in |revoked|'s extension list. +// X509_REVOKED_get_ext_d2i behaves like `X509V3_get_d2i` but looks for the +// extension in `revoked`'s extension list. // // WARNING: This function is difficult to use correctly. See the documentation -// for |X509V3_get_d2i| for details. +// for `X509V3_get_d2i` for details. OPENSSL_EXPORT void *X509_REVOKED_get_ext_d2i(const X509_REVOKED *revoked, int nid, int *out_critical, int *out_idx); -// X509_REVOKED_add1_ext_i2d behaves like |X509V3_add1_i2d| but adds the -// extension to |x|'s extension list. +// X509_REVOKED_add1_ext_i2d behaves like `X509V3_add1_i2d` but adds the +// extension to `x`'s extension list. // // WARNING: This function may return zero or -1 on error. The caller must also -// ensure |value|'s type matches |nid|. See the documentation for -// |X509V3_add1_i2d| for details. +// ensure `value`'s type matches `nid`. See the documentation for +// `X509V3_add1_i2d` for details. OPENSSL_EXPORT int X509_REVOKED_add1_ext_i2d(X509_REVOKED *x, int nid, void *value, int crit, unsigned long flags); @@ -1059,245 +1059,245 @@ // Certificate requests. // -// An |X509_REQ| represents a PKCS #10 certificate request (RFC 2986). These are +// An `X509_REQ` represents a PKCS #10 certificate request (RFC 2986). These are // also referred to as certificate signing requests or CSRs. CSRs are a common // format used to request a certificate from a CA. // -// Although an |X509_REQ| is a mutable object, mutating an |X509_REQ| can give -// incorrect results. Callers typically obtain |X509_REQ|s by parsing some input -// with |d2i_X509_REQ|, etc. Such objects carry information such as the +// Although an `X509_REQ` is a mutable object, mutating an `X509_REQ` can give +// incorrect results. Callers typically obtain `X509_REQ`s by parsing some input +// with `d2i_X509_REQ`, etc. Such objects carry information such as the // serialized CertificationRequestInfo, which will become inconsistent when // mutated. // // Instead, mutation functions should only be used when issuing new CRLs, as // described in a later section. -// X509_REQ_dup returns a newly-allocated copy of |req|, or NULL on error. This -// function works by serializing the structure, so if |req| is incomplete, it +// X509_REQ_dup returns a newly-allocated copy of `req`, or NULL on error. This +// function works by serializing the structure, so if `req` is incomplete, it // may fail. OPENSSL_EXPORT X509_REQ *X509_REQ_dup(const X509_REQ *req); -// X509_REQ_free releases memory associated with |req|. +// X509_REQ_free releases memory associated with `req`. OPENSSL_EXPORT void X509_REQ_free(X509_REQ *req); -// d2i_X509_REQ parses up to |len| bytes from |*inp| as a DER-encoded -// CertificateRequest (RFC 2986), as described in |d2i_SAMPLE|. +// d2i_X509_REQ parses up to `len` bytes from `*inp` as a DER-encoded +// CertificateRequest (RFC 2986), as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509_REQ *d2i_X509_REQ(X509_REQ **out, const uint8_t **inp, long len); -// i2d_X509_REQ marshals |req| as a CertificateRequest (RFC 2986), as described -// in |i2d_SAMPLE|. +// i2d_X509_REQ marshals `req` as a CertificateRequest (RFC 2986), as described +// in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509_REQ(const X509_REQ *req, uint8_t **outp); -// X509_REQ_VERSION_1 is the version constant for |X509_REQ| objects. No other +// X509_REQ_VERSION_1 is the version constant for `X509_REQ` objects. No other // versions are defined. #define X509_REQ_VERSION_1 0 -// X509_REQ_get_version returns the numerical value of |req|'s version. This -// will always be |X509_REQ_VERSION_1| for valid CSRs. For compatibility, -// |d2i_X509_REQ| also accepts some invalid version numbers, in which case this +// X509_REQ_get_version returns the numerical value of `req`'s version. This +// will always be `X509_REQ_VERSION_1` for valid CSRs. For compatibility, +// `d2i_X509_REQ` also accepts some invalid version numbers, in which case this // function may return other values. OPENSSL_EXPORT long X509_REQ_get_version(const X509_REQ *req); -// X509_REQ_get_subject_name returns |req|'s subject name. Note this function is +// X509_REQ_get_subject_name returns `req`'s subject name. Note this function is // not const-correct for legacy reasons. OPENSSL_EXPORT X509_NAME *X509_REQ_get_subject_name(const X509_REQ *req); -// X509_REQ_get0_pubkey returns |req|'s public key as an |EVP_PKEY|, or NULL if -// the public key was unsupported or could not be decoded. The |EVP_PKEY| is -// cached in |req|, so callers must not mutate the result. +// X509_REQ_get0_pubkey returns `req`'s public key as an `EVP_PKEY`, or NULL if +// the public key was unsupported or could not be decoded. The `EVP_PKEY` is +// cached in `req`, so callers must not mutate the result. OPENSSL_EXPORT EVP_PKEY *X509_REQ_get0_pubkey(const X509_REQ *req); -// X509_REQ_get_pubkey behaves like |X509_REQ_get0_pubkey| but increments the -// reference count on the |EVP_PKEY|. The caller must release the result with -// |EVP_PKEY_free| when done. The |EVP_PKEY| is cached in |req|, so callers must +// X509_REQ_get_pubkey behaves like `X509_REQ_get0_pubkey` but increments the +// reference count on the `EVP_PKEY`. The caller must release the result with +// `EVP_PKEY_free` when done. The `EVP_PKEY` is cached in `req`, so callers must // not mutate the result. OPENSSL_EXPORT EVP_PKEY *X509_REQ_get_pubkey(const X509_REQ *req); -// X509_REQ_check_private_key returns one if |req|'s public key matches |pkey| +// X509_REQ_check_private_key returns one if `req`'s public key matches `pkey` // and zero otherwise. OPENSSL_EXPORT int X509_REQ_check_private_key(const X509_REQ *req, const EVP_PKEY *pkey); -// X509_REQ_get_attr_count returns the number of attributes in |req|. +// X509_REQ_get_attr_count returns the number of attributes in `req`. OPENSSL_EXPORT int X509_REQ_get_attr_count(const X509_REQ *req); -// X509_REQ_get_attr returns the attribute at index |loc| in |req|, or NULL if +// X509_REQ_get_attr returns the attribute at index `loc` in `req`, or NULL if // out of bounds. OPENSSL_EXPORT X509_ATTRIBUTE *X509_REQ_get_attr(const X509_REQ *req, int loc); -// X509_REQ_get_attr_by_NID returns the index of the attribute in |req| of type -// |nid|, or a negative number if not found. If found, callers can use -// |X509_REQ_get_attr| to look up the attribute by index. +// X509_REQ_get_attr_by_NID returns the index of the attribute in `req` of type +// `nid`, or a negative number if not found. If found, callers can use +// `X509_REQ_get_attr` to look up the attribute by index. // -// If |lastpos| is non-negative, it begins searching at |lastpos| + 1. Callers +// If `lastpos` is non-negative, it begins searching at `lastpos` + 1. Callers // can thus loop over all matching attributes by first passing -1 and then // passing the previously-returned value until no match is returned. OPENSSL_EXPORT int X509_REQ_get_attr_by_NID(const X509_REQ *req, int nid, int lastpos); -// X509_REQ_get_attr_by_OBJ behaves like |X509_REQ_get_attr_by_NID| but looks -// for attributes of type |obj|. +// X509_REQ_get_attr_by_OBJ behaves like `X509_REQ_get_attr_by_NID` but looks +// for attributes of type `obj`. OPENSSL_EXPORT int X509_REQ_get_attr_by_OBJ(const X509_REQ *req, const ASN1_OBJECT *obj, int lastpos); -// X509_REQ_extension_nid returns one if |nid| is a supported CSR attribute type +// X509_REQ_extension_nid returns one if `nid` is a supported CSR attribute type // for carrying extensions and zero otherwise. The supported types are -// |NID_ext_req| (pkcs-9-at-extensionRequest from RFC 2985) and |NID_ms_ext_req| +// `NID_ext_req` (pkcs-9-at-extensionRequest from RFC 2985) and `NID_ms_ext_req` // (a Microsoft szOID_CERT_EXTENSIONS variant). OPENSSL_EXPORT int X509_REQ_extension_nid(int nid); // X509_REQ_get_extensions decodes the most preferred list of requested -// extensions in |req| and returns a newly-allocated |STACK_OF(X509_EXTENSION)| -// containing the result. It returns NULL on error, or if |req| did not request +// extensions in `req` and returns a newly-allocated `STACK_OF(X509_EXTENSION)` +// containing the result. It returns NULL on error, or if `req` did not request // extensions. // // CSRs do not store extensions directly. Instead there are attribute types -// which are defined to hold extensions. See |X509_REQ_extension_nid|. This +// which are defined to hold extensions. See `X509_REQ_extension_nid`. This // function supports both pkcs-9-at-extensionRequest from RFC 2985 and the // Microsoft szOID_CERT_EXTENSIONS variant. If both are present, // pkcs-9-at-extensionRequest is preferred. OPENSSL_EXPORT STACK_OF(X509_EXTENSION) *X509_REQ_get_extensions( const X509_REQ *req); -// X509_REQ_get0_signature sets |*out_sig| and |*out_alg| to the signature and -// signature algorithm of |req|, respectively. Either output pointer may be NULL +// X509_REQ_get0_signature sets `*out_sig` and `*out_alg` to the signature and +// signature algorithm of `req`, respectively. Either output pointer may be NULL // to ignore the value. OPENSSL_EXPORT void X509_REQ_get0_signature(const X509_REQ *req, const ASN1_BIT_STRING **out_sig, const X509_ALGOR **out_alg); -// X509_REQ_get_signature_nid returns the NID corresponding to |req|'s signature -// algorithm, or |NID_undef| if the signature algorithm does not correspond to +// X509_REQ_get_signature_nid returns the NID corresponding to `req`'s signature +// algorithm, or `NID_undef` if the signature algorithm does not correspond to // a known NID. OPENSSL_EXPORT int X509_REQ_get_signature_nid(const X509_REQ *req); -// X509_REQ_verify checks that |req| has a valid signature by |pkey|. It returns +// X509_REQ_verify checks that `req` has a valid signature by `pkey`. It returns // one if the signature is valid and zero otherwise. OPENSSL_EXPORT int X509_REQ_verify(const X509_REQ *req, EVP_PKEY *pkey); // X509_REQ_get1_email returns a newly-allocated list of NUL-terminated strings -// containing all email addresses in |req|'s subject and all rfc822name names -// in |req|'s subject alternative names. The subject alternative names extension -// is extracted from the result of |X509_REQ_get_extensions|. Email addresses +// containing all email addresses in `req`'s subject and all rfc822name names +// in `req`'s subject alternative names. The subject alternative names extension +// is extracted from the result of `X509_REQ_get_extensions`. Email addresses // which contain embedded NUL bytes are skipped. The results are returned in an // arbitrary order. // // On error, or if there are no such email addresses, it returns NULL. When -// done, the caller must release the result with |X509_email_free|. +// done, the caller must release the result with `X509_email_free`. OPENSSL_EXPORT STACK_OF(OPENSSL_STRING) *X509_REQ_get1_email( const X509_REQ *req); // Issuing certificate requests. // -// An |X509_REQ| object may also represent an incomplete CSR. Callers may -// construct empty |X509_REQ| objects, fill in fields individually, and finally +// An `X509_REQ` object may also represent an incomplete CSR. Callers may +// construct empty `X509_REQ` objects, fill in fields individually, and finally // sign the result. The following functions may be used for this purpose. -// X509_REQ_new returns a newly-allocated, empty |X509_REQ| object, or NULL on +// X509_REQ_new returns a newly-allocated, empty `X509_REQ` object, or NULL on // error. This object may be filled in and then signed to construct a CSR. OPENSSL_EXPORT X509_REQ *X509_REQ_new(void); -// X509_REQ_set_version sets |req|'s version to |version|, which should be -// |X509_REQ_VERSION_1|. It returns one on success and zero on error. +// X509_REQ_set_version sets `req`'s version to `version`, which should be +// `X509_REQ_VERSION_1`. It returns one on success and zero on error. // -// The only defined CSR version is |X509_REQ_VERSION_1|, so there is no need to +// The only defined CSR version is `X509_REQ_VERSION_1`, so there is no need to // call this function. OPENSSL_EXPORT int X509_REQ_set_version(X509_REQ *req, long version); -// X509_REQ_set_subject_name sets |req|'s subject to a copy of |name|. It +// X509_REQ_set_subject_name sets `req`'s subject to a copy of `name`. It // returns one on success and zero on error. OPENSSL_EXPORT int X509_REQ_set_subject_name(X509_REQ *req, X509_NAME *name); -// X509_REQ_set_pubkey sets |req|'s public key to |pkey|. It returns one on -// success and zero on error. This function does not take ownership of |pkey| +// X509_REQ_set_pubkey sets `req`'s public key to `pkey`. It returns one on +// success and zero on error. This function does not take ownership of `pkey` // and internally copies and updates reference counts as needed. OPENSSL_EXPORT int X509_REQ_set_pubkey(X509_REQ *req, EVP_PKEY *pkey); -// X509_REQ_delete_attr removes the attribute at index |loc| in |req|. It -// returns the removed attribute to the caller, or NULL if |loc| was out of +// X509_REQ_delete_attr removes the attribute at index `loc` in `req`. It +// returns the removed attribute to the caller, or NULL if `loc` was out of // bounds. If non-NULL, the caller must release the result with -// |X509_ATTRIBUTE_free| when done. It is also safe, but not necessary, to call -// |X509_ATTRIBUTE_free| if the result is NULL. +// `X509_ATTRIBUTE_free` when done. It is also safe, but not necessary, to call +// `X509_ATTRIBUTE_free` if the result is NULL. OPENSSL_EXPORT X509_ATTRIBUTE *X509_REQ_delete_attr(X509_REQ *req, int loc); -// X509_REQ_add1_attr appends a copy of |attr| to |req|'s list of attributes. It +// X509_REQ_add1_attr appends a copy of `attr` to `req`'s list of attributes. It // returns one on success and zero on error. OPENSSL_EXPORT int X509_REQ_add1_attr(X509_REQ *req, const X509_ATTRIBUTE *attr); -// X509_REQ_add1_attr_by_OBJ appends a new attribute to |req| with type |obj|. +// X509_REQ_add1_attr_by_OBJ appends a new attribute to `req` with type `obj`. // It returns one on success and zero on error. The value is determined by -// |X509_ATTRIBUTE_set1_data|. +// `X509_ATTRIBUTE_set1_data`. // -// WARNING: The interpretation of |attrtype|, |data|, and |len| is complex and -// error-prone. See |X509_ATTRIBUTE_set1_data| for details. +// WARNING: The interpretation of `attrtype`, `data`, and `len` is complex and +// error-prone. See `X509_ATTRIBUTE_set1_data` for details. OPENSSL_EXPORT int X509_REQ_add1_attr_by_OBJ(X509_REQ *req, const ASN1_OBJECT *obj, int attrtype, const unsigned char *data, int len); -// X509_REQ_add1_attr_by_NID behaves like |X509_REQ_add1_attr_by_OBJ| except the -// attribute type is determined by |nid|. +// X509_REQ_add1_attr_by_NID behaves like `X509_REQ_add1_attr_by_OBJ` except the +// attribute type is determined by `nid`. OPENSSL_EXPORT int X509_REQ_add1_attr_by_NID(X509_REQ *req, int nid, int attrtype, const unsigned char *data, int len); -// X509_REQ_add1_attr_by_txt behaves like |X509_REQ_add1_attr_by_OBJ| except the -// attribute type is determined by calling |OBJ_txt2obj| with |attrname|. +// X509_REQ_add1_attr_by_txt behaves like `X509_REQ_add1_attr_by_OBJ` except the +// attribute type is determined by calling `OBJ_txt2obj` with `attrname`. OPENSSL_EXPORT int X509_REQ_add1_attr_by_txt(X509_REQ *req, const char *attrname, int attrtype, const unsigned char *data, int len); -// X509_REQ_add_extensions_nid adds an attribute to |req| of type |nid|, to -// request the certificate extensions in |exts|. It returns one on success and -// zero on error. |nid| should be |NID_ext_req| or |NID_ms_ext_req|. +// X509_REQ_add_extensions_nid adds an attribute to `req` of type `nid`, to +// request the certificate extensions in `exts`. It returns one on success and +// zero on error. `nid` should be `NID_ext_req` or `NID_ms_ext_req`. OPENSSL_EXPORT int X509_REQ_add_extensions_nid( X509_REQ *req, const STACK_OF(X509_EXTENSION) *exts, int nid); -// X509_REQ_add_extensions behaves like |X509_REQ_add_extensions_nid|, using the -// standard |NID_ext_req| for the attribute type. +// X509_REQ_add_extensions behaves like `X509_REQ_add_extensions_nid`, using the +// standard `NID_ext_req` for the attribute type. OPENSSL_EXPORT int X509_REQ_add_extensions( X509_REQ *req, const STACK_OF(X509_EXTENSION) *exts); -// X509_REQ_sign signs |req| with |pkey| and replaces the signature algorithm +// X509_REQ_sign signs `req` with `pkey` and replaces the signature algorithm // and signature fields. It returns the length of the signature on success and -// zero on error. This function uses digest algorithm |md|, or |pkey|'s default -// if NULL. Other signing parameters use |pkey|'s defaults. To customize them, -// use |X509_REQ_sign_ctx|. +// zero on error. This function uses digest algorithm `md`, or `pkey`'s default +// if NULL. Other signing parameters use `pkey`'s defaults. To customize them, +// use `X509_REQ_sign_ctx`. OPENSSL_EXPORT int X509_REQ_sign(X509_REQ *req, EVP_PKEY *pkey, const EVP_MD *md); -// X509_REQ_sign_ctx signs |req| with |ctx| and replaces the signature algorithm +// X509_REQ_sign_ctx signs `req` with `ctx` and replaces the signature algorithm // and signature fields. It returns the length of the signature on success and -// zero on error. The signature algorithm and parameters come from |ctx|, which -// must have been initialized with |EVP_DigestSignInit|. The caller should -// configure the corresponding |EVP_PKEY_CTX| before calling this function. +// zero on error. The signature algorithm and parameters come from `ctx`, which +// must have been initialized with `EVP_DigestSignInit`. The caller should +// configure the corresponding `EVP_PKEY_CTX` before calling this function. // -// On success or failure, this function mutates |ctx| and resets it to the empty +// On success or failure, this function mutates `ctx` and resets it to the empty // state. Caller should not rely on its contents after the function returns. OPENSSL_EXPORT int X509_REQ_sign_ctx(X509_REQ *req, EVP_MD_CTX *ctx); // i2d_re_X509_REQ_tbs serializes the CertificationRequestInfo (see RFC 2986) -// portion of |req|, as described in |i2d_SAMPLE|. +// portion of `req`, as described in `i2d_SAMPLE`. // // This function re-encodes the CertificationRequestInfo and may not reflect -// |req|'s original encoding. It may be used to manually generate a signature +// `req`'s original encoding. It may be used to manually generate a signature // for a new certificate request. OPENSSL_EXPORT int i2d_re_X509_REQ_tbs(X509_REQ *req, uint8_t **outp); -// X509_REQ_set1_signature_algo sets |req|'s signature algorithm to |algo| and +// X509_REQ_set1_signature_algo sets `req`'s signature algorithm to `algo` and // returns one on success or zero on error. OPENSSL_EXPORT int X509_REQ_set1_signature_algo(X509_REQ *req, const X509_ALGOR *algo); -// X509_REQ_set1_signature_value sets |req|'s signature to a copy of the -// |sig_len| bytes pointed by |sig|. It returns one on success and zero on +// X509_REQ_set1_signature_value sets `req`'s signature to a copy of the +// `sig_len` bytes pointed by `sig`. It returns one on success and zero on // error. // // Due to a specification error, PKCS#10 certificate requests store signatures @@ -1312,7 +1312,7 @@ // Names. // -// An |X509_NAME| represents an X.509 Name structure (RFC 5280). X.509 names are +// An `X509_NAME` represents an X.509 Name structure (RFC 5280). X.509 names are // a complex, hierarchical structure over a collection of attributes. Each name // is sequence of relative distinguished names (RDNs), decreasing in // specificity. For example, the first RDN may specify the country, while the @@ -1322,10 +1322,10 @@ // OBJECT IDENTIFIERs. This determines the ASN.1 type of the value, which is // commonly a string but may be other types. // -// The |X509_NAME| representation flattens this two-level structure into a -// single list of attributes. Each attribute is stored in an |X509_NAME_ENTRY|, +// The `X509_NAME` representation flattens this two-level structure into a +// single list of attributes. Each attribute is stored in an `X509_NAME_ENTRY`, // with also maintains the index of the RDN it is part of, accessible via -// |X509_NAME_ENTRY_set|. This can be used to recover the two-level structure. +// `X509_NAME_ENTRY_set`. This can be used to recover the two-level structure. // // X.509 names are largely vestigial. Historically, DNS names were parsed out of // the subject's common name attribute, but this is deprecated and has since @@ -1335,30 +1335,30 @@ DEFINE_STACK_OF(X509_NAME_ENTRY) DEFINE_STACK_OF(X509_NAME) -// X509_NAME is an |ASN1_ITEM| whose ASN.1 type is X.509 Name (RFC 5280) and C -// type is |X509_NAME*|. +// X509_NAME is an `ASN1_ITEM` whose ASN.1 type is X.509 Name (RFC 5280) and C +// type is `X509_NAME*`. DECLARE_ASN1_ITEM(X509_NAME) -// X509_NAME_new returns a new, empty |X509_NAME|, or NULL on error. +// X509_NAME_new returns a new, empty `X509_NAME`, or NULL on error. OPENSSL_EXPORT X509_NAME *X509_NAME_new(void); -// X509_NAME_free releases memory associated with |name|. +// X509_NAME_free releases memory associated with `name`. OPENSSL_EXPORT void X509_NAME_free(X509_NAME *name); -// d2i_X509_NAME parses up to |len| bytes from |*inp| as a DER-encoded X.509 -// Name (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_X509_NAME parses up to `len` bytes from `*inp` as a DER-encoded X.509 +// Name (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509_NAME *d2i_X509_NAME(X509_NAME **out, const uint8_t **inp, long len); -// i2d_X509_NAME marshals |in| as a DER-encoded X.509 Name (RFC 5280), as -// described in |i2d_SAMPLE|. +// i2d_X509_NAME marshals `in` as a DER-encoded X.509 Name (RFC 5280), as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509_NAME(const X509_NAME *in, uint8_t **outp); -// X509_NAME_dup returns a newly-allocated copy of |name|, or NULL on error. +// X509_NAME_dup returns a newly-allocated copy of `name`, or NULL on error. OPENSSL_EXPORT X509_NAME *X509_NAME_dup(const X509_NAME *name); -// X509_NAME_cmp compares |a| and |b|'s canonicalized forms. It returns zero if -// they are equal, one if |a| sorts after |b|, -1 if |b| sorts after |a|, and -2 +// X509_NAME_cmp compares `a` and `b`'s canonicalized forms. It returns zero if +// they are equal, one if `a` sorts after `b`, -1 if `b` sorts after `a`, and -2 // on error. // // TODO(https://crbug.com/boringssl/355): The -2 return is very inconvenient to @@ -1367,173 +1367,173 @@ // Although even the library itself passes this to a sorting function. OPENSSL_EXPORT int X509_NAME_cmp(const X509_NAME *a, const X509_NAME *b); -// X509_NAME_get0_der marshals |name| as a DER-encoded X.509 Name (RFC 5280). On -// success, it returns one and sets |*out_der| and |*out_der_len| to a buffer -// containing the result. Otherwise, it returns zero. |*out_der| is owned by -// |name| and must not be freed by the caller. It is invalidated after |name| is +// X509_NAME_get0_der marshals `name` as a DER-encoded X.509 Name (RFC 5280). On +// success, it returns one and sets `*out_der` and `*out_der_len` to a buffer +// containing the result. Otherwise, it returns zero. `*out_der` is owned by +// `name` and must not be freed by the caller. It is invalidated after `name` is // mutated or freed. OPENSSL_EXPORT int X509_NAME_get0_der(const X509_NAME *name, const uint8_t **out_der, size_t *out_der_len); -// X509_NAME_set makes a copy of |name|. On success, it frees |*xn|, sets |*xn| +// X509_NAME_set makes a copy of `name`. On success, it frees `*xn`, sets `*xn` // to the copy, and returns one. Otherwise, it returns zero. OPENSSL_EXPORT int X509_NAME_set(X509_NAME **xn, const X509_NAME *name); -// X509_NAME_entry_count returns the number of entries in |name|. +// X509_NAME_entry_count returns the number of entries in `name`. OPENSSL_EXPORT int X509_NAME_entry_count(const X509_NAME *name); // X509_NAME_get_index_by_NID returns the zero-based index of the first -// attribute in |name| with type |nid|, or -1 if there is none. |nid| should be -// one of the |NID_*| constants. If |lastpos| is non-negative, it begins -// searching at |lastpos+1|. To search all attributes, pass in -1, not zero. +// attribute in `name` with type `nid`, or -1 if there is none. `nid` should be +// one of the `NID_*` constants. If `lastpos` is non-negative, it begins +// searching at `lastpos+1`. To search all attributes, pass in -1, not zero. // -// Indices from this function refer to |X509_NAME|'s flattened representation. +// Indices from this function refer to `X509_NAME`'s flattened representation. OPENSSL_EXPORT int X509_NAME_get_index_by_NID(const X509_NAME *name, int nid, int lastpos); -// X509_NAME_get_index_by_OBJ behaves like |X509_NAME_get_index_by_NID| but -// looks for attributes with type |obj|. +// X509_NAME_get_index_by_OBJ behaves like `X509_NAME_get_index_by_NID` but +// looks for attributes with type `obj`. OPENSSL_EXPORT int X509_NAME_get_index_by_OBJ(const X509_NAME *name, const ASN1_OBJECT *obj, int lastpos); -// X509_NAME_get_entry returns the attribute in |name| at index |loc|, or NULL -// if |loc| is out of range. |loc| is interpreted using |X509_NAME|'s flattened +// X509_NAME_get_entry returns the attribute in `name` at index `loc`, or NULL +// if `loc` is out of range. `loc` is interpreted using `X509_NAME`'s flattened // representation. This function returns a non-const pointer for OpenSSL // compatibility, but callers should not mutate the result. Doing so will break // internal invariants in the library. OPENSSL_EXPORT X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc); -// X509_NAME_delete_entry removes and returns the attribute in |name| at index -// |loc|, or NULL if |loc| is out of range. |loc| is interpreted using -// |X509_NAME|'s flattened representation. If the attribute is found, the caller -// is responsible for releasing the result with |X509_NAME_ENTRY_free|. +// X509_NAME_delete_entry removes and returns the attribute in `name` at index +// `loc`, or NULL if `loc` is out of range. `loc` is interpreted using +// `X509_NAME`'s flattened representation. If the attribute is found, the caller +// is responsible for releasing the result with `X509_NAME_ENTRY_free`. // -// This function will internally update RDN indices (see |X509_NAME_ENTRY_set|) +// This function will internally update RDN indices (see `X509_NAME_ENTRY_set`) // so they continue to be consecutive. OPENSSL_EXPORT X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc); -// X509_NAME_add_entry adds a copy of |entry| to |name| and returns one on -// success or zero on error. If |loc| is -1, the entry is appended to |name|. -// Otherwise, it is inserted at index |loc|. If |set| is -1, the entry is added +// X509_NAME_add_entry adds a copy of `entry` to `name` and returns one on +// success or zero on error. If `loc` is -1, the entry is appended to `name`. +// Otherwise, it is inserted at index `loc`. If `set` is -1, the entry is added // to the previous entry's RDN. If it is 0, the entry becomes a singleton RDN. // If 1, it is added to next entry's RDN. // -// This function will internally update RDN indices (see |X509_NAME_ENTRY_set|) +// This function will internally update RDN indices (see `X509_NAME_ENTRY_set`) // so they continue to be consecutive. OPENSSL_EXPORT int X509_NAME_add_entry(X509_NAME *name, const X509_NAME_ENTRY *entry, int loc, int set); -// X509_NAME_add_entry_by_OBJ adds a new entry to |name| and returns one on -// success or zero on error. The entry's attribute type is |obj|. The entry's -// attribute value is determined by |type|, |bytes|, and |len|, as in -// |X509_NAME_ENTRY_set_data|. The entry's position is determined by |loc| and -// |set| as in |X509_NAME_add_entry|. +// X509_NAME_add_entry_by_OBJ adds a new entry to `name` and returns one on +// success or zero on error. The entry's attribute type is `obj`. The entry's +// attribute value is determined by `type`, `bytes`, and `len`, as in +// `X509_NAME_ENTRY_set_data`. The entry's position is determined by `loc` and +// `set` as in `X509_NAME_add_entry`. OPENSSL_EXPORT int X509_NAME_add_entry_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int type, const uint8_t *bytes, ossl_ssize_t len, int loc, int set); -// X509_NAME_add_entry_by_NID behaves like |X509_NAME_add_entry_by_OBJ| but sets -// the entry's attribute type to |nid|, which should be one of the |NID_*| +// X509_NAME_add_entry_by_NID behaves like `X509_NAME_add_entry_by_OBJ` but sets +// the entry's attribute type to `nid`, which should be one of the `NID_*` // constants. OPENSSL_EXPORT int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, const uint8_t *bytes, ossl_ssize_t len, int loc, int set); -// X509_NAME_add_entry_by_txt behaves like |X509_NAME_add_entry_by_OBJ| but sets -// the entry's attribute type to |field|, which is passed to |OBJ_txt2obj|. +// X509_NAME_add_entry_by_txt behaves like `X509_NAME_add_entry_by_OBJ` but sets +// the entry's attribute type to `field`, which is passed to `OBJ_txt2obj`. OPENSSL_EXPORT int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const uint8_t *bytes, ossl_ssize_t len, int loc, int set); -// X509_NAME_ENTRY_new returns a new, empty |X509_NAME_ENTRY|, or NULL on error. +// X509_NAME_ENTRY_new returns a new, empty `X509_NAME_ENTRY`, or NULL on error. OPENSSL_EXPORT X509_NAME_ENTRY *X509_NAME_ENTRY_new(void); -// X509_NAME_ENTRY_free releases memory associated with |entry|. +// X509_NAME_ENTRY_free releases memory associated with `entry`. OPENSSL_EXPORT void X509_NAME_ENTRY_free(X509_NAME_ENTRY *entry); -// X509_NAME_ENTRY_dup returns a newly-allocated copy of |entry|, or NULL on +// X509_NAME_ENTRY_dup returns a newly-allocated copy of `entry`, or NULL on // error. OPENSSL_EXPORT X509_NAME_ENTRY *X509_NAME_ENTRY_dup( const X509_NAME_ENTRY *entry); -// X509_NAME_ENTRY_get_object returns |entry|'s attribute type. This function +// X509_NAME_ENTRY_get_object returns `entry`'s attribute type. This function // returns a non-const pointer for OpenSSL compatibility, but callers should not // mutate the result. Doing so will break internal invariants in the library. OPENSSL_EXPORT ASN1_OBJECT *X509_NAME_ENTRY_get_object( const X509_NAME_ENTRY *entry); -// X509_NAME_ENTRY_set_object sets |entry|'s attribute type to |obj|. It returns +// X509_NAME_ENTRY_set_object sets `entry`'s attribute type to `obj`. It returns // one on success and zero on error. OPENSSL_EXPORT int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *entry, const ASN1_OBJECT *obj); -// X509_NAME_ENTRY_get_data returns |entry|'s attribute value, represented as an -// |ASN1_STRING|. This value may have any ASN.1 type, so callers must check the +// X509_NAME_ENTRY_get_data returns `entry`'s attribute value, represented as an +// `ASN1_STRING`. This value may have any ASN.1 type, so callers must check the // type before interpreting the contents. This function returns a non-const // pointer for OpenSSL compatibility, but callers should not mutate the result. // Doing so will break internal invariants in the library. // -// See |ASN1_STRING| for how values are represented in this library. Where a -// specific |ASN1_STRING| representation exists, that representation is used. -// Otherwise, the |V_ASN1_OTHER| representation is used. Note that NULL, OBJECT -// IDENTIFIER, and BOOLEAN attribute values are represented as |V_ASN1_OTHER|, +// See `ASN1_STRING` for how values are represented in this library. Where a +// specific `ASN1_STRING` representation exists, that representation is used. +// Otherwise, the `V_ASN1_OTHER` representation is used. Note that NULL, OBJECT +// IDENTIFIER, and BOOLEAN attribute values are represented as `V_ASN1_OTHER`, // because their usual representation in this library is not -// |ASN1_STRING|-compatible. +// `ASN1_STRING`-compatible. OPENSSL_EXPORT ASN1_STRING *X509_NAME_ENTRY_get_data( const X509_NAME_ENTRY *entry); -// X509_NAME_ENTRY_set_data sets |entry|'s value to |len| bytes from |bytes|. It -// returns one on success and zero on error. If |len| is -1, |bytes| must be a -// NUL-terminated C string and the length is determined by |strlen|. |bytes| is +// X509_NAME_ENTRY_set_data sets `entry`'s value to `len` bytes from `bytes`. It +// returns one on success and zero on error. If `len` is -1, `bytes` must be a +// NUL-terminated C string and the length is determined by `strlen`. `bytes` is // converted to an ASN.1 type as follows: // -// If |type| is a |MBSTRING_*| constant, the value is an ASN.1 string. The -// string is determined by decoding |bytes| in the encoding specified by |type|, -// and then re-encoding it in a form appropriate for |entry|'s attribute type. -// See |ASN1_STRING_set_by_NID| for details. +// If `type` is a `MBSTRING_*` constant, the value is an ASN.1 string. The +// string is determined by decoding `bytes` in the encoding specified by `type`, +// and then re-encoding it in a form appropriate for `entry`'s attribute type. +// See `ASN1_STRING_set_by_NID` for details. // -// Otherwise, the value is an |ASN1_STRING| with type |type| and value |bytes|. -// See |ASN1_STRING| for how to format ASN.1 types as an |ASN1_STRING|. If -// |type| is |V_ASN1_UNDEF| the previous |ASN1_STRING| type is reused. +// Otherwise, the value is an `ASN1_STRING` with type `type` and value `bytes`. +// See `ASN1_STRING` for how to format ASN.1 types as an `ASN1_STRING`. If +// `type` is `V_ASN1_UNDEF` the previous `ASN1_STRING` type is reused. OPENSSL_EXPORT int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *entry, int type, const uint8_t *bytes, ossl_ssize_t len); // X509_NAME_ENTRY_set returns the zero-based index of the RDN which contains -// |entry|. Consecutive entries with the same index are part of the same RDN. +// `entry`. Consecutive entries with the same index are part of the same RDN. OPENSSL_EXPORT int X509_NAME_ENTRY_set(const X509_NAME_ENTRY *entry); -// X509_NAME_ENTRY_create_by_OBJ creates a new |X509_NAME_ENTRY| with attribute -// type |obj|. The attribute value is determined from |type|, |bytes|, and |len| -// as in |X509_NAME_ENTRY_set_data|. It returns the |X509_NAME_ENTRY| on success +// X509_NAME_ENTRY_create_by_OBJ creates a new `X509_NAME_ENTRY` with attribute +// type `obj`. The attribute value is determined from `type`, `bytes`, and `len` +// as in `X509_NAME_ENTRY_set_data`. It returns the `X509_NAME_ENTRY` on success // and NULL on error. // -// If |out| is non-NULL and |*out| is NULL, it additionally sets |*out| to the -// result on success. If both |out| and |*out| are non-NULL, it updates the -// object at |*out| instead of allocating a new one. +// If `out` is non-NULL and `*out` is NULL, it additionally sets `*out` to the +// result on success. If both `out` and `*out` are non-NULL, it updates the +// object at `*out` instead of allocating a new one. OPENSSL_EXPORT X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ( X509_NAME_ENTRY **out, const ASN1_OBJECT *obj, int type, const uint8_t *bytes, ossl_ssize_t len); -// X509_NAME_ENTRY_create_by_NID behaves like |X509_NAME_ENTRY_create_by_OBJ| -// except the attribute type is |nid|, which should be one of the |NID_*| +// X509_NAME_ENTRY_create_by_NID behaves like `X509_NAME_ENTRY_create_by_OBJ` +// except the attribute type is `nid`, which should be one of the `NID_*` // constants. OPENSSL_EXPORT X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID( X509_NAME_ENTRY **out, int nid, int type, const uint8_t *bytes, ossl_ssize_t len); -// X509_NAME_ENTRY_create_by_txt behaves like |X509_NAME_ENTRY_create_by_OBJ| -// except the attribute type is |field|, which is passed to |OBJ_txt2obj|. +// X509_NAME_ENTRY_create_by_txt behaves like `X509_NAME_ENTRY_create_by_OBJ` +// except the attribute type is `field`, which is passed to `OBJ_txt2obj`. OPENSSL_EXPORT X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt( X509_NAME_ENTRY **out, const char *field, int type, const uint8_t *bytes, ossl_ssize_t len); @@ -1542,74 +1542,74 @@ // Public keys. // // X.509 encodes public keys as SubjectPublicKeyInfo (RFC 5280), sometimes -// referred to as SPKI. These are represented in this library by |X509_PUBKEY|. +// referred to as SPKI. These are represented in this library by `X509_PUBKEY`. -// X509_PUBKEY_new returns a newly-allocated, empty |X509_PUBKEY| object, or +// X509_PUBKEY_new returns a newly-allocated, empty `X509_PUBKEY` object, or // NULL on error. OPENSSL_EXPORT X509_PUBKEY *X509_PUBKEY_new(void); -// X509_PUBKEY_free releases memory associated with |key|. +// X509_PUBKEY_free releases memory associated with `key`. OPENSSL_EXPORT void X509_PUBKEY_free(X509_PUBKEY *key); -// d2i_X509_PUBKEY parses up to |len| bytes from |*inp| as a DER-encoded -// SubjectPublicKeyInfo, as described in |d2i_SAMPLE|. +// d2i_X509_PUBKEY parses up to `len` bytes from `*inp` as a DER-encoded +// SubjectPublicKeyInfo, as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509_PUBKEY *d2i_X509_PUBKEY(X509_PUBKEY **out, const uint8_t **inp, long len); -// i2d_X509_PUBKEY marshals |key| as a DER-encoded SubjectPublicKeyInfo, as -// described in |i2d_SAMPLE|. +// i2d_X509_PUBKEY marshals `key` as a DER-encoded SubjectPublicKeyInfo, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509_PUBKEY(const X509_PUBKEY *key, uint8_t **outp); -// X509_PUBKEY_set serializes |pkey| into a newly-allocated |X509_PUBKEY| -// structure. On success, it frees |*x| if non-NULL, then sets |*x| to the new +// X509_PUBKEY_set serializes `pkey` into a newly-allocated `X509_PUBKEY` +// structure. On success, it frees `*x` if non-NULL, then sets `*x` to the new // object, and returns one. Otherwise, it returns zero. OPENSSL_EXPORT int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey); -// X509_PUBKEY_get0 returns |key| as an |EVP_PKEY|, or NULL if |key| either -// could not be parsed or is an unrecognized algorithm. The |EVP_PKEY| is cached -// in |key|, so callers must not mutate the result. +// X509_PUBKEY_get0 returns `key` as an `EVP_PKEY`, or NULL if `key` either +// could not be parsed or is an unrecognized algorithm. The `EVP_PKEY` is cached +// in `key`, so callers must not mutate the result. OPENSSL_EXPORT EVP_PKEY *X509_PUBKEY_get0(const X509_PUBKEY *key); -// X509_PUBKEY_get behaves like |X509_PUBKEY_get0| but increments the reference -// count on the |EVP_PKEY|. The caller must release the result with -// |EVP_PKEY_free| when done. The |EVP_PKEY| is cached in |key|, so callers must +// X509_PUBKEY_get behaves like `X509_PUBKEY_get0` but increments the reference +// count on the `EVP_PKEY`. The caller must release the result with +// `EVP_PKEY_free` when done. The `EVP_PKEY` is cached in `key`, so callers must // not mutate the result. OPENSSL_EXPORT EVP_PKEY *X509_PUBKEY_get(const X509_PUBKEY *key); -// X509_PUBKEY_set0_param sets |pub| to a key with AlgorithmIdentifier -// determined by |obj|, |param_type|, and |param_value|, and an encoded -// public key of |key|. On success, it gives |pub| ownership of all the other -// parameters and returns one. Otherwise, it returns zero. |key| must have been -// allocated by |OPENSSL_malloc|. |obj| and, if applicable, |param_value| must +// X509_PUBKEY_set0_param sets `pub` to a key with AlgorithmIdentifier +// determined by `obj`, `param_type`, and `param_value`, and an encoded +// public key of `key`. On success, it gives `pub` ownership of all the other +// parameters and returns one. Otherwise, it returns zero. `key` must have been +// allocated by `OPENSSL_malloc`. `obj` and, if applicable, `param_value` must // not be freed after a successful call, and must have been allocated in a -// manner compatible with |ASN1_OBJECT_free| or |ASN1_STRING_free|. +// manner compatible with `ASN1_OBJECT_free` or `ASN1_STRING_free`. // -// |obj|, |param_type|, and |param_value| are interpreted as in -// |X509_ALGOR_set0|. See |X509_ALGOR_set0| for details. +// `obj`, `param_type`, and `param_value` are interpreted as in +// `X509_ALGOR_set0`. See `X509_ALGOR_set0` for details. OPENSSL_EXPORT int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *obj, int param_type, void *param_value, uint8_t *key, int key_len); -// X509_PUBKEY_get0_param outputs fields of |pub| and returns one. If |out_obj| -// is not NULL, it sets |*out_obj| to AlgorithmIdentifier's OID. If |out_key| -// is not NULL, it sets |*out_key| and |*out_key_len| to the encoded public key. -// If |out_alg| is not NULL, it sets |*out_alg| to the AlgorithmIdentifier. +// X509_PUBKEY_get0_param outputs fields of `pub` and returns one. If `out_obj` +// is not NULL, it sets `*out_obj` to AlgorithmIdentifier's OID. If `out_key` +// is not NULL, it sets `*out_key` and `*out_key_len` to the encoded public key. +// If `out_alg` is not NULL, it sets `*out_alg` to the AlgorithmIdentifier. // -// All pointers outputted by this function are internal to |pub| and must not be +// All pointers outputted by this function are internal to `pub` and must not be // freed by the caller. Additionally, although some outputs are non-const, // callers must not mutate the resulting objects. // // Note: X.509 SubjectPublicKeyInfo structures store the encoded public key as a -// BIT STRING. |*out_key| and |*out_key_len| will silently pad the key with zero -// bits if |pub| did not contain a whole number of bytes. Use -// |X509_PUBKEY_get0_public_key| to preserve this information. +// BIT STRING. `*out_key` and `*out_key_len` will silently pad the key with zero +// bits if `pub` did not contain a whole number of bytes. Use +// `X509_PUBKEY_get0_public_key` to preserve this information. OPENSSL_EXPORT int X509_PUBKEY_get0_param(ASN1_OBJECT **out_obj, const uint8_t **out_key, int *out_key_len, X509_ALGOR **out_alg, X509_PUBKEY *pub); -// X509_PUBKEY_get0_public_key returns |pub|'s encoded public key. +// X509_PUBKEY_get0_public_key returns `pub`'s encoded public key. OPENSSL_EXPORT const ASN1_BIT_STRING *X509_PUBKEY_get0_public_key( const X509_PUBKEY *pub); @@ -1617,79 +1617,79 @@ // Extensions. // // X.509 certificates and CRLs may contain a list of extensions (RFC 5280). -// Extensions have a type, specified by an object identifier (|ASN1_OBJECT|) and +// Extensions have a type, specified by an object identifier (`ASN1_OBJECT`) and // a byte string value, which should a DER-encoded structure whose type is // determined by the extension type. This library represents extensions with the -// |X509_EXTENSION| type. +// `X509_EXTENSION` type. -// X509_EXTENSION is an |ASN1_ITEM| whose ASN.1 type is X.509 Extension (RFC -// 5280) and C type is |X509_EXTENSION*|. +// X509_EXTENSION is an `ASN1_ITEM` whose ASN.1 type is X.509 Extension (RFC +// 5280) and C type is `X509_EXTENSION*`. DECLARE_ASN1_ITEM(X509_EXTENSION) -// X509_EXTENSION_new returns a newly-allocated, empty |X509_EXTENSION| object +// X509_EXTENSION_new returns a newly-allocated, empty `X509_EXTENSION` object // or NULL on error. OPENSSL_EXPORT X509_EXTENSION *X509_EXTENSION_new(void); -// X509_EXTENSION_free releases memory associated with |ex|. +// X509_EXTENSION_free releases memory associated with `ex`. OPENSSL_EXPORT void X509_EXTENSION_free(X509_EXTENSION *ex); -// d2i_X509_EXTENSION parses up to |len| bytes from |*inp| as a DER-encoded -// X.509 Extension (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_X509_EXTENSION parses up to `len` bytes from `*inp` as a DER-encoded +// X.509 Extension (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509_EXTENSION *d2i_X509_EXTENSION(X509_EXTENSION **out, const uint8_t **inp, long len); -// i2d_X509_EXTENSION marshals |ex| as a DER-encoded X.509 Extension (RFC -// 5280), as described in |i2d_SAMPLE|. +// i2d_X509_EXTENSION marshals `ex` as a DER-encoded X.509 Extension (RFC +// 5280), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509_EXTENSION(const X509_EXTENSION *ex, uint8_t **outp); -// X509_EXTENSION_dup returns a newly-allocated copy of |ex|, or NULL on error. -// This function works by serializing the structure, so if |ex| is incomplete, +// X509_EXTENSION_dup returns a newly-allocated copy of `ex`, or NULL on error. +// This function works by serializing the structure, so if `ex` is incomplete, // it may fail. OPENSSL_EXPORT X509_EXTENSION *X509_EXTENSION_dup(const X509_EXTENSION *ex); -// X509_EXTENSION_create_by_NID creates a new |X509_EXTENSION| with type |nid|, -// value |data|, and critical bit |crit|. It returns an |X509_EXTENSION| on -// success, and NULL on error. |nid| should be a |NID_*| constant. +// X509_EXTENSION_create_by_NID creates a new `X509_EXTENSION` with type `nid`, +// value `data`, and critical bit `crit`. It returns an `X509_EXTENSION` on +// success, and NULL on error. `nid` should be a `NID_*` constant. // -// If |ex| and |*ex| are both non-NULL, |*ex| is used to hold the result, -// otherwise a new object is allocated. If |ex| is non-NULL and |*ex| is NULL, -// the function sets |*ex| to point to the newly allocated result, in addition +// If `ex` and `*ex` are both non-NULL, `*ex` is used to hold the result, +// otherwise a new object is allocated. If `ex` is non-NULL and `*ex` is NULL, +// the function sets `*ex` to point to the newly allocated result, in addition // to returning the result. OPENSSL_EXPORT X509_EXTENSION *X509_EXTENSION_create_by_NID( X509_EXTENSION **ex, int nid, int crit, const ASN1_OCTET_STRING *data); -// X509_EXTENSION_create_by_OBJ behaves like |X509_EXTENSION_create_by_NID|, but -// the extension type is determined by an |ASN1_OBJECT|. +// X509_EXTENSION_create_by_OBJ behaves like `X509_EXTENSION_create_by_NID`, but +// the extension type is determined by an `ASN1_OBJECT`. OPENSSL_EXPORT X509_EXTENSION *X509_EXTENSION_create_by_OBJ( X509_EXTENSION **ex, const ASN1_OBJECT *obj, int crit, const ASN1_OCTET_STRING *data); -// X509_EXTENSION_get_object returns |ex|'s extension type. This function +// X509_EXTENSION_get_object returns `ex`'s extension type. This function // returns a non-const pointer for OpenSSL compatibility, but callers should not // mutate the result. OPENSSL_EXPORT ASN1_OBJECT *X509_EXTENSION_get_object(const X509_EXTENSION *ex); -// X509_EXTENSION_get_data returns |ne|'s extension value. This function returns +// X509_EXTENSION_get_data returns `ne`'s extension value. This function returns // a non-const pointer for OpenSSL compatibility, but callers should not mutate // the result. OPENSSL_EXPORT ASN1_OCTET_STRING *X509_EXTENSION_get_data( const X509_EXTENSION *ne); -// X509_EXTENSION_get_critical returns one if |ex| is critical and zero +// X509_EXTENSION_get_critical returns one if `ex` is critical and zero // otherwise. OPENSSL_EXPORT int X509_EXTENSION_get_critical(const X509_EXTENSION *ex); -// X509_EXTENSION_set_object sets |ex|'s extension type to |obj|. It returns one +// X509_EXTENSION_set_object sets `ex`'s extension type to `obj`. It returns one // on success and zero on error. OPENSSL_EXPORT int X509_EXTENSION_set_object(X509_EXTENSION *ex, const ASN1_OBJECT *obj); -// X509_EXTENSION_set_critical sets |ex| to critical if |crit| is non-zero and -// to non-critical if |crit| is zero. +// X509_EXTENSION_set_critical sets `ex` to critical if `crit` is non-zero and +// to non-critical if `crit` is zero. OPENSSL_EXPORT int X509_EXTENSION_set_critical(X509_EXTENSION *ex, int crit); -// X509_EXTENSION_set_data set's |ex|'s extension value to a copy of |data|. It +// X509_EXTENSION_set_data set's `ex`'s extension value to a copy of `data`. It // returns one on success and zero on error. OPENSSL_EXPORT int X509_EXTENSION_set_data(X509_EXTENSION *ex, const ASN1_OCTET_STRING *data); @@ -1698,70 +1698,70 @@ // Extension lists. // // The following functions manipulate lists of extensions. Most of them have -// corresponding functions on the containing |X509|, |X509_CRL|, or -// |X509_REVOKED|. +// corresponding functions on the containing `X509`, `X509_CRL`, or +// `X509_REVOKED`. DEFINE_STACK_OF(X509_EXTENSION) typedef STACK_OF(X509_EXTENSION) X509_EXTENSIONS; -// d2i_X509_EXTENSIONS parses up to |len| bytes from |*inp| as a DER-encoded -// SEQUENCE OF Extension (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_X509_EXTENSIONS parses up to `len` bytes from `*inp` as a DER-encoded +// SEQUENCE OF Extension (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509_EXTENSIONS *d2i_X509_EXTENSIONS(X509_EXTENSIONS **out, const uint8_t **inp, long len); -// i2d_X509_EXTENSIONS marshals |alg| as a DER-encoded SEQUENCE OF Extension -// (RFC 5280), as described in |i2d_SAMPLE|. +// i2d_X509_EXTENSIONS marshals `alg` as a DER-encoded SEQUENCE OF Extension +// (RFC 5280), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509_EXTENSIONS(const X509_EXTENSIONS *alg, uint8_t **outp); -// X509v3_get_ext_count returns the number of extensions in |x|. +// X509v3_get_ext_count returns the number of extensions in `x`. OPENSSL_EXPORT int X509v3_get_ext_count(const STACK_OF(X509_EXTENSION) *x); -// X509v3_get_ext_by_NID returns the index of the first extension in |x| with -// type |nid|, or a negative number if not found. If found, callers can use -// |X509v3_get_ext| to look up the extension by index. +// X509v3_get_ext_by_NID returns the index of the first extension in `x` with +// type `nid`, or a negative number if not found. If found, callers can use +// `X509v3_get_ext` to look up the extension by index. // -// If |lastpos| is non-negative, it begins searching at |lastpos| + 1. Callers +// If `lastpos` is non-negative, it begins searching at `lastpos` + 1. Callers // can thus loop over all matching extensions by first passing -1 and then // passing the previously-returned value until no match is returned. OPENSSL_EXPORT int X509v3_get_ext_by_NID(const STACK_OF(X509_EXTENSION) *x, int nid, int lastpos); -// X509v3_get_ext_by_OBJ behaves like |X509v3_get_ext_by_NID| but looks for -// extensions matching |obj|. +// X509v3_get_ext_by_OBJ behaves like `X509v3_get_ext_by_NID` but looks for +// extensions matching `obj`. OPENSSL_EXPORT int X509v3_get_ext_by_OBJ(const STACK_OF(X509_EXTENSION) *x, const ASN1_OBJECT *obj, int lastpos); -// X509v3_get_ext_by_critical returns the index of the first extension in |x| -// whose critical bit matches |crit|, or a negative number if no such extension +// X509v3_get_ext_by_critical returns the index of the first extension in `x` +// whose critical bit matches `crit`, or a negative number if no such extension // was found. // -// If |lastpos| is non-negative, it begins searching at |lastpos| + 1. Callers +// If `lastpos` is non-negative, it begins searching at `lastpos` + 1. Callers // can thus loop over all matching extensions by first passing -1 and then // passing the previously-returned value until no match is returned. OPENSSL_EXPORT int X509v3_get_ext_by_critical(const STACK_OF(X509_EXTENSION) *x, int crit, int lastpos); -// X509v3_get_ext returns the extension in |x| at index |loc|, or NULL if |loc| +// X509v3_get_ext returns the extension in `x` at index `loc`, or NULL if `loc` // is out of bounds. This function returns a non-const pointer for OpenSSL // compatibility, but callers should not mutate the result. OPENSSL_EXPORT X509_EXTENSION *X509v3_get_ext(const STACK_OF(X509_EXTENSION) *x, int loc); -// X509v3_delete_ext removes the extension in |x| at index |loc| and returns the -// removed extension, or NULL if |loc| was out of bounds. If an extension was -// returned, the caller must release it with |X509_EXTENSION_free|. +// X509v3_delete_ext removes the extension in `x` at index `loc` and returns the +// removed extension, or NULL if `loc` was out of bounds. If an extension was +// returned, the caller must release it with `X509_EXTENSION_free`. OPENSSL_EXPORT X509_EXTENSION *X509v3_delete_ext(STACK_OF(X509_EXTENSION) *x, int loc); -// X509v3_add_ext adds a copy of |ex| to the extension list in |*x|. If |*x| is -// NULL, it allocates a new |STACK_OF(X509_EXTENSION)| to hold the copy and sets -// |*x| to the new list. It returns |*x| on success and NULL on error. The -// caller retains ownership of |ex| and can release it independently of |*x|. +// X509v3_add_ext adds a copy of `ex` to the extension list in `*x`. If `*x` is +// NULL, it allocates a new `STACK_OF(X509_EXTENSION)` to hold the copy and sets +// `*x` to the new list. It returns `*x` on success and NULL on error. The +// caller retains ownership of `ex` and can release it independently of `*x`. // -// The new extension is inserted at index |loc|, shifting extensions to the -// right. If |loc| is -1 or out of bounds, the new extension is appended to the +// The new extension is inserted at index `loc`, shifting extensions to the +// right. If `loc` is -1 or out of bounds, the new extension is appended to the // list. OPENSSL_EXPORT STACK_OF(X509_EXTENSION) *X509v3_add_ext( STACK_OF(X509_EXTENSION) **x, const X509_EXTENSION *ex, int loc); @@ -1772,111 +1772,111 @@ // Several functions in the library encode and decode extension values into a // C structure to that extension. The following extensions are supported: // -// - |NID_authority_key_identifier| with type |AUTHORITY_KEYID| -// - |NID_basic_constraints| with type |BASIC_CONSTRAINTS| -// - |NID_certificate_issuer| with type |GENERAL_NAMES| -// - |NID_certificate_policies| with type |CERTIFICATEPOLICIES| -// - |NID_crl_distribution_points| with type |CRL_DIST_POINTS| -// - |NID_crl_number| with type |ASN1_INTEGER| -// - |NID_crl_reason| with type |ASN1_ENUMERATED| -// - |NID_delta_crl| with type |ASN1_INTEGER| -// - |NID_ext_key_usage| with type |EXTENDED_KEY_USAGE| -// - |NID_freshest_crl| with type |ISSUING_DIST_POINT| -// - |NID_id_pkix_OCSP_noCheck| with type |ASN1_NULL| -// - |NID_info_access| with type |AUTHORITY_INFO_ACCESS| -// - |NID_inhibit_any_policy| with type |ASN1_INTEGER| -// - |NID_invalidity_date| with type |ASN1_GENERALIZEDTIME| -// - |NID_issuer_alt_name| with type |GENERAL_NAMES| -// - |NID_issuing_distribution_point| with type |ISSUING_DIST_POINT| -// - |NID_key_usage| with type |ASN1_BIT_STRING| -// - |NID_name_constraints| with type |NAME_CONSTRAINTS| -// - |NID_netscape_base_url| with type |ASN1_IA5STRING| -// - |NID_netscape_ca_policy_url| with type |ASN1_IA5STRING| -// - |NID_netscape_ca_revocation_url| with type |ASN1_IA5STRING| -// - |NID_netscape_cert_type| with type |ASN1_BIT_STRING| -// - |NID_netscape_comment| with type |ASN1_IA5STRING| -// - |NID_netscape_renewal_url| with type |ASN1_IA5STRING| -// - |NID_netscape_revocation_url| with type |ASN1_IA5STRING| -// - |NID_netscape_ssl_server_name| with type |ASN1_IA5STRING| -// - |NID_policy_constraints| with type |POLICY_CONSTRAINTS| -// - |NID_policy_mappings| with type |POLICY_MAPPINGS| -// - |NID_sinfo_access| with type |AUTHORITY_INFO_ACCESS| -// - |NID_subject_alt_name| with type |GENERAL_NAMES| -// - |NID_subject_key_identifier| with type |ASN1_OCTET_STRING| +// - `NID_authority_key_identifier` with type `AUTHORITY_KEYID` +// - `NID_basic_constraints` with type `BASIC_CONSTRAINTS` +// - `NID_certificate_issuer` with type `GENERAL_NAMES` +// - `NID_certificate_policies` with type `CERTIFICATEPOLICIES` +// - `NID_crl_distribution_points` with type `CRL_DIST_POINTS` +// - `NID_crl_number` with type `ASN1_INTEGER` +// - `NID_crl_reason` with type `ASN1_ENUMERATED` +// - `NID_delta_crl` with type `ASN1_INTEGER` +// - `NID_ext_key_usage` with type `EXTENDED_KEY_USAGE` +// - `NID_freshest_crl` with type `ISSUING_DIST_POINT` +// - `NID_id_pkix_OCSP_noCheck` with type `ASN1_NULL` +// - `NID_info_access` with type `AUTHORITY_INFO_ACCESS` +// - `NID_inhibit_any_policy` with type `ASN1_INTEGER` +// - `NID_invalidity_date` with type `ASN1_GENERALIZEDTIME` +// - `NID_issuer_alt_name` with type `GENERAL_NAMES` +// - `NID_issuing_distribution_point` with type `ISSUING_DIST_POINT` +// - `NID_key_usage` with type `ASN1_BIT_STRING` +// - `NID_name_constraints` with type `NAME_CONSTRAINTS` +// - `NID_netscape_base_url` with type `ASN1_IA5STRING` +// - `NID_netscape_ca_policy_url` with type `ASN1_IA5STRING` +// - `NID_netscape_ca_revocation_url` with type `ASN1_IA5STRING` +// - `NID_netscape_cert_type` with type `ASN1_BIT_STRING` +// - `NID_netscape_comment` with type `ASN1_IA5STRING` +// - `NID_netscape_renewal_url` with type `ASN1_IA5STRING` +// - `NID_netscape_revocation_url` with type `ASN1_IA5STRING` +// - `NID_netscape_ssl_server_name` with type `ASN1_IA5STRING` +// - `NID_policy_constraints` with type `POLICY_CONSTRAINTS` +// - `NID_policy_mappings` with type `POLICY_MAPPINGS` +// - `NID_sinfo_access` with type `AUTHORITY_INFO_ACCESS` +// - `NID_subject_alt_name` with type `GENERAL_NAMES` +// - `NID_subject_key_identifier` with type `ASN1_OCTET_STRING` // // If an extension does not appear in this list, e.g. for a custom extension, -// callers can instead use functions such as |X509_get_ext_by_OBJ|, -// |X509_EXTENSION_get_data|, and |X509_EXTENSION_create_by_OBJ| to inspect or -// create extensions directly. Although the |X509V3_EXT_METHOD| mechanism allows +// callers can instead use functions such as `X509_get_ext_by_OBJ`, +// `X509_EXTENSION_get_data`, and `X509_EXTENSION_create_by_OBJ` to inspect or +// create extensions directly. Although the `X509V3_EXT_METHOD` mechanism allows // registering custom extensions, doing so is deprecated and may result in // threading or memory errors. -// X509V3_EXT_d2i decodes |ext| and returns a pointer to a newly-allocated +// X509V3_EXT_d2i decodes `ext` and returns a pointer to a newly-allocated // structure, with type dependent on the type of the extension. It returns NULL -// if |ext| is an unsupported extension or if there was a syntax error in the +// if `ext` is an unsupported extension or if there was a syntax error in the // extension. The caller should cast the return value to the expected type and // free the structure when done. // // WARNING: Casting the return value to the wrong type is a potentially // exploitable memory error, so callers must not use this function before -// checking |ext| is of a known type. See the list at the top of this section +// checking `ext` is of a known type. See the list at the top of this section // for the correct types. OPENSSL_EXPORT void *X509V3_EXT_d2i(const X509_EXTENSION *ext); -// X509V3_get_d2i finds and decodes the extension in |extensions| of type |nid|. +// X509V3_get_d2i finds and decodes the extension in `extensions` of type `nid`. // If found, it decodes it and returns a newly-allocated structure, with type -// dependent on |nid|. If the extension is not found or on error, it returns -// NULL. The caller may distinguish these cases using the |out_critical| value. +// dependent on `nid`. If the extension is not found or on error, it returns +// NULL. The caller may distinguish these cases using the `out_critical` value. // -// If |out_critical| is not NULL, this function sets |*out_critical| to one if +// If `out_critical` is not NULL, this function sets `*out_critical` to one if // the extension is found and critical, zero if it is found and not critical, -1 // if it is not found, and -2 if there is an invalid duplicate extension. Note -// this function may set |*out_critical| to one or zero and still return NULL if +// this function may set `*out_critical` to one or zero and still return NULL if // the extension is found but has a syntax error. // -// If |out_idx| is not NULL, this function looks for the first occurrence of the -// extension after |*out_idx|. It then sets |*out_idx| to the index of the -// extension, or -1 if not found. If |out_idx| is non-NULL, duplicate extensions +// If `out_idx` is not NULL, this function looks for the first occurrence of the +// extension after `*out_idx`. It then sets `*out_idx` to the index of the +// extension, or -1 if not found. If `out_idx` is non-NULL, duplicate extensions // are not treated as an error. Callers, however, should not rely on this // behavior as it may be removed in the future. Duplicate extensions are // forbidden in RFC 5280. // // WARNING: This function is difficult to use correctly. Callers should pass a -// non-NULL |out_critical| and check both the return value and |*out_critical| -// to handle errors. If the return value is NULL and |*out_critical| is not -1, +// non-NULL `out_critical` and check both the return value and `*out_critical` +// to handle errors. If the return value is NULL and `*out_critical` is not -1, // there was an error. Otherwise, the function succeeded and but may return NULL -// for a missing extension. Callers should pass NULL to |out_idx| so that +// for a missing extension. Callers should pass NULL to `out_idx` so that // duplicate extensions are handled correctly. // // Additionally, casting the return value to the wrong type is a potentially -// exploitable memory error, so callers must ensure the cast and |nid| match. +// exploitable memory error, so callers must ensure the cast and `nid` match. // See the list at the top of this section for the correct types. OPENSSL_EXPORT void *X509V3_get_d2i(const STACK_OF(X509_EXTENSION) *extensions, int nid, int *out_critical, int *out_idx); -// X509V3_EXT_free casts |ext_data| into the type that corresponds to |nid| and +// X509V3_EXT_free casts `ext_data` into the type that corresponds to `nid` and // releases memory associated with it. It returns one on success and zero if -// |nid| is not a known extension. +// `nid` is not a known extension. // -// WARNING: Casting |ext_data| to the wrong type is a potentially exploitable -// memory error, so callers must ensure |ext_data|'s type matches |nid|. See the +// WARNING: Casting `ext_data` to the wrong type is a potentially exploitable +// memory error, so callers must ensure `ext_data`'s type matches `nid`. See the // list at the top of this section for the correct types. // // TODO(davidben): OpenSSL upstream no longer exposes this function. Remove it? OPENSSL_EXPORT int X509V3_EXT_free(int nid, void *ext_data); -// X509V3_EXT_i2d casts |ext_struc| into the type that corresponds to -// |ext_nid|, serializes it, and returns a newly-allocated |X509_EXTENSION| -// object containing the serialization, or NULL on error. The |X509_EXTENSION| -// has OID |ext_nid| and is critical if |crit| is one. +// X509V3_EXT_i2d casts `ext_struc` into the type that corresponds to +// `ext_nid`, serializes it, and returns a newly-allocated `X509_EXTENSION` +// object containing the serialization, or NULL on error. The `X509_EXTENSION` +// has OID `ext_nid` and is critical if `crit` is one. // -// WARNING: Casting |ext_struc| to the wrong type is a potentially exploitable -// memory error, so callers must ensure |ext_struct|'s type matches |ext_nid|. +// WARNING: Casting `ext_struc` to the wrong type is a potentially exploitable +// memory error, so callers must ensure `ext_struct`'s type matches `ext_nid`. // See the list at the top of this section for the correct types. OPENSSL_EXPORT X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc); -// The following constants control the behavior of |X509V3_add1_i2d| and related +// The following constants control the behavior of `X509V3_add1_i2d` and related // functions. // X509V3_ADD_OP_MASK can be ANDed with the flags to determine how duplicate @@ -1905,7 +1905,7 @@ // X509V3_ADD_DELETE causes the function to remove the matching extension. No // new extension is added. If there is no matching extension, the function -// fails. The |value| parameter is ignored in this mode. +// fails. The `value` parameter is ignored in this mode. #define X509V3_ADD_DELETE 5L // X509V3_ADD_SILENT may be ORed into one of the values above to indicate the @@ -1914,18 +1914,18 @@ // continue to return -1 and add to the error queue on other errors. #define X509V3_ADD_SILENT 0x10 -// X509V3_add1_i2d casts |value| to the type that corresponds to |nid|, -// serializes it, and appends it to the extension list in |*x|. If |*x| is NULL, -// it will set |*x| to a newly-allocated |STACK_OF(X509_EXTENSION)| as needed. -// The |crit| parameter determines whether the new extension is critical. -// |flags| may be some combination of the |X509V3_ADD_*| constants to control +// X509V3_add1_i2d casts `value` to the type that corresponds to `nid`, +// serializes it, and appends it to the extension list in `*x`. If `*x` is NULL, +// it will set `*x` to a newly-allocated `STACK_OF(X509_EXTENSION)` as needed. +// The `crit` parameter determines whether the new extension is critical. +// `flags` may be some combination of the `X509V3_ADD_*` constants to control // the function's behavior on duplicate extension. // // This function returns one on success, zero if the operation failed due to a // missing or duplicate extension, and -1 on other errors. // -// WARNING: Casting |value| to the wrong type is a potentially exploitable -// memory error, so callers must ensure |value|'s type matches |nid|. See the +// WARNING: Casting `value` to the wrong type is a potentially exploitable +// memory error, so callers must ensure `value`'s type matches `nid`. See the // list at the top of this section for the correct types. OPENSSL_EXPORT int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value, int crit, unsigned long flags); @@ -1937,32 +1937,32 @@ // whether a certificate is a CA certificate and, if so, optionally constrains // the maximum depth of the certificate chain. -// A BASIC_CONSTRAINTS_st, aka |BASIC_CONSTRAINTS| represents an +// A BASIC_CONSTRAINTS_st, aka `BASIC_CONSTRAINTS` represents an // BasicConstraints structure (RFC 5280). struct BASIC_CONSTRAINTS_st { ASN1_BOOLEAN ca; ASN1_INTEGER *pathlen; } /* BASIC_CONSTRAINTS */; -// BASIC_CONSTRAINTS is an |ASN1_ITEM| whose ASN.1 type is BasicConstraints (RFC -// 5280) and C type is |BASIC_CONSTRAINTS*|. +// BASIC_CONSTRAINTS is an `ASN1_ITEM` whose ASN.1 type is BasicConstraints (RFC +// 5280) and C type is `BASIC_CONSTRAINTS*`. DECLARE_ASN1_ITEM(BASIC_CONSTRAINTS) -// BASIC_CONSTRAINTS_new returns a newly-allocated, empty |BASIC_CONSTRAINTS| +// BASIC_CONSTRAINTS_new returns a newly-allocated, empty `BASIC_CONSTRAINTS` // object, or NULL on error. OPENSSL_EXPORT BASIC_CONSTRAINTS *BASIC_CONSTRAINTS_new(void); -// BASIC_CONSTRAINTS_free releases memory associated with |bcons|. +// BASIC_CONSTRAINTS_free releases memory associated with `bcons`. OPENSSL_EXPORT void BASIC_CONSTRAINTS_free(BASIC_CONSTRAINTS *bcons); -// d2i_BASIC_CONSTRAINTS parses up to |len| bytes from |*inp| as a DER-encoded -// BasicConstraints (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_BASIC_CONSTRAINTS parses up to `len` bytes from `*inp` as a DER-encoded +// BasicConstraints (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT BASIC_CONSTRAINTS *d2i_BASIC_CONSTRAINTS(BASIC_CONSTRAINTS **out, const uint8_t **inp, long len); -// i2d_BASIC_CONSTRAINTS marshals |bcons| as a DER-encoded BasicConstraints (RFC -// 5280), as described in |i2d_SAMPLE|. +// i2d_BASIC_CONSTRAINTS marshals `bcons` as a DER-encoded BasicConstraints (RFC +// 5280), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_BASIC_CONSTRAINTS(const BASIC_CONSTRAINTS *bcons, uint8_t **outp); @@ -1975,39 +1975,39 @@ typedef STACK_OF(ASN1_OBJECT) EXTENDED_KEY_USAGE; -// EXTENDED_KEY_USAGE is an |ASN1_ITEM| whose ASN.1 type is ExtKeyUsageSyntax -// (RFC 5280) and C type is |STACK_OF(ASN1_OBJECT)*|, or |EXTENDED_KEY_USAGE*|. +// EXTENDED_KEY_USAGE is an `ASN1_ITEM` whose ASN.1 type is ExtKeyUsageSyntax +// (RFC 5280) and C type is `STACK_OF(ASN1_OBJECT)*`, or `EXTENDED_KEY_USAGE*`. DECLARE_ASN1_ITEM(EXTENDED_KEY_USAGE) -// EXTENDED_KEY_USAGE_new returns a newly-allocated, empty |EXTENDED_KEY_USAGE| +// EXTENDED_KEY_USAGE_new returns a newly-allocated, empty `EXTENDED_KEY_USAGE` // object, or NULL on error. OPENSSL_EXPORT EXTENDED_KEY_USAGE *EXTENDED_KEY_USAGE_new(void); -// EXTENDED_KEY_USAGE_free releases memory associated with |eku|. +// EXTENDED_KEY_USAGE_free releases memory associated with `eku`. OPENSSL_EXPORT void EXTENDED_KEY_USAGE_free(EXTENDED_KEY_USAGE *eku); -// d2i_EXTENDED_KEY_USAGE parses up to |len| bytes from |*inp| as a DER-encoded -// ExtKeyUsageSyntax (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_EXTENDED_KEY_USAGE parses up to `len` bytes from `*inp` as a DER-encoded +// ExtKeyUsageSyntax (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT EXTENDED_KEY_USAGE *d2i_EXTENDED_KEY_USAGE( EXTENDED_KEY_USAGE **out, const uint8_t **inp, long len); -// i2d_EXTENDED_KEY_USAGE marshals |eku| as a DER-encoded ExtKeyUsageSyntax (RFC -// 5280), as described in |i2d_SAMPLE|. +// i2d_EXTENDED_KEY_USAGE marshals `eku` as a DER-encoded ExtKeyUsageSyntax (RFC +// 5280), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_EXTENDED_KEY_USAGE(const EXTENDED_KEY_USAGE *eku, uint8_t **outp); // General names. // -// A |GENERAL_NAME| represents an X.509 GeneralName structure, defined in RFC -// 5280, Section 4.2.1.6. General names are distinct from names (|X509_NAME|). A +// A `GENERAL_NAME` represents an X.509 GeneralName structure, defined in RFC +// 5280, Section 4.2.1.6. General names are distinct from names (`X509_NAME`). A // general name is a CHOICE type which may contain one of several name types, // most commonly a DNS name or an IP address. General names most commonly appear // in the subject alternative name (SAN) extension, though they are also used in // other extensions. // // Many extensions contain a SEQUENCE OF GeneralName, or GeneralNames, so -// |STACK_OF(GENERAL_NAME)| is defined and aliased to |GENERAL_NAMES|. +// `STACK_OF(GENERAL_NAME)` is defined and aliased to `GENERAL_NAMES`. typedef struct otherName_st { ASN1_OBJECT *type_id; @@ -2019,7 +2019,7 @@ ASN1_STRING *partyName; } EDIPARTYNAME; -// GEN_* are constants for the |type| field of |GENERAL_NAME|, defined below. +// GEN_* are constants for the `type` field of `GENERAL_NAME`, defined below. #define GEN_OTHERNAME 0 #define GEN_EMAIL 1 #define GEN_DNS 2 @@ -2030,13 +2030,13 @@ #define GEN_IPADD 7 #define GEN_RID 8 -// A GENERAL_NAME_st, aka |GENERAL_NAME|, represents an X.509 GeneralName. The -// |type| field determines which member of |d| is active. A |GENERAL_NAME| may -// also be empty, in which case |type| is -1 and |d| is NULL. Empty -// |GENERAL_NAME|s are invalid and will never be returned from the parser, but -// may be created temporarily, e.g. by |GENERAL_NAME_new|. +// A GENERAL_NAME_st, aka `GENERAL_NAME`, represents an X.509 GeneralName. The +// `type` field determines which member of `d` is active. A `GENERAL_NAME` may +// also be empty, in which case `type` is -1 and `d` is NULL. Empty +// `GENERAL_NAME`s are invalid and will never be returned from the parser, but +// may be created temporarily, e.g. by `GENERAL_NAME_new`. // -// WARNING: |type| and |d| must be kept consistent. An inconsistency will result +// WARNING: `type` and `d` must be kept consistent. An inconsistency will result // in a potentially exploitable memory error. struct GENERAL_NAME_st { int type; @@ -2060,75 +2060,75 @@ } d; } /* GENERAL_NAME */; -// GENERAL_NAME_new returns a new, empty |GENERAL_NAME|, or NULL on error. +// GENERAL_NAME_new returns a new, empty `GENERAL_NAME`, or NULL on error. OPENSSL_EXPORT GENERAL_NAME *GENERAL_NAME_new(void); -// GENERAL_NAME_free releases memory associated with |gen|. +// GENERAL_NAME_free releases memory associated with `gen`. OPENSSL_EXPORT void GENERAL_NAME_free(GENERAL_NAME *gen); -// d2i_GENERAL_NAME parses up to |len| bytes from |*inp| as a DER-encoded X.509 -// GeneralName (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_GENERAL_NAME parses up to `len` bytes from `*inp` as a DER-encoded X.509 +// GeneralName (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT GENERAL_NAME *d2i_GENERAL_NAME(GENERAL_NAME **out, const uint8_t **inp, long len); -// i2d_GENERAL_NAME marshals |in| as a DER-encoded X.509 GeneralName (RFC 5280), -// as described in |i2d_SAMPLE|. +// i2d_GENERAL_NAME marshals `in` as a DER-encoded X.509 GeneralName (RFC 5280), +// as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_GENERAL_NAME(const GENERAL_NAME *in, uint8_t **outp); -// GENERAL_NAME_dup returns a newly-allocated copy of |gen|, or NULL on error. -// This function works by serializing the structure, so it will fail if |gen| is +// GENERAL_NAME_dup returns a newly-allocated copy of `gen`, or NULL on error. +// This function works by serializing the structure, so it will fail if `gen` is // empty. OPENSSL_EXPORT GENERAL_NAME *GENERAL_NAME_dup(const GENERAL_NAME *gen); -// GENERAL_NAMES_new returns a new, empty |GENERAL_NAMES|, or NULL on error. +// GENERAL_NAMES_new returns a new, empty `GENERAL_NAMES`, or NULL on error. OPENSSL_EXPORT GENERAL_NAMES *GENERAL_NAMES_new(void); -// GENERAL_NAMES_free releases memory associated with |gens|. +// GENERAL_NAMES_free releases memory associated with `gens`. OPENSSL_EXPORT void GENERAL_NAMES_free(GENERAL_NAMES *gens); -// d2i_GENERAL_NAMES parses up to |len| bytes from |*inp| as a DER-encoded -// SEQUENCE OF GeneralName, as described in |d2i_SAMPLE|. +// d2i_GENERAL_NAMES parses up to `len` bytes from `*inp` as a DER-encoded +// SEQUENCE OF GeneralName, as described in `d2i_SAMPLE`. OPENSSL_EXPORT GENERAL_NAMES *d2i_GENERAL_NAMES(GENERAL_NAMES **out, const uint8_t **inp, long len); -// i2d_GENERAL_NAMES marshals |in| as a DER-encoded SEQUENCE OF GeneralName, as -// described in |i2d_SAMPLE|. +// i2d_GENERAL_NAMES marshals `in` as a DER-encoded SEQUENCE OF GeneralName, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_GENERAL_NAMES(const GENERAL_NAMES *in, uint8_t **outp); -// OTHERNAME_new returns a new, empty |OTHERNAME|, or NULL on error. +// OTHERNAME_new returns a new, empty `OTHERNAME`, or NULL on error. OPENSSL_EXPORT OTHERNAME *OTHERNAME_new(void); -// OTHERNAME_free releases memory associated with |name|. +// OTHERNAME_free releases memory associated with `name`. OPENSSL_EXPORT void OTHERNAME_free(OTHERNAME *name); -// EDIPARTYNAME_new returns a new, empty |EDIPARTYNAME|, or NULL on error. +// EDIPARTYNAME_new returns a new, empty `EDIPARTYNAME`, or NULL on error. // EDIPartyName is rarely used in practice, so callers are unlikely to need this // function. OPENSSL_EXPORT EDIPARTYNAME *EDIPARTYNAME_new(void); -// EDIPARTYNAME_free releases memory associated with |name|. EDIPartyName is +// EDIPARTYNAME_free releases memory associated with `name`. EDIPartyName is // rarely used in practice, so callers are unlikely to need this function. OPENSSL_EXPORT void EDIPARTYNAME_free(EDIPARTYNAME *name); -// GENERAL_NAME_set0_value set |gen|'s type and value to |type| and |value|. -// |type| must be a |GEN_*| constant and |value| must be an object of the -// corresponding type. |gen| takes ownership of |value|, so |value| must have +// GENERAL_NAME_set0_value set `gen`'s type and value to `type` and `value`. +// `type` must be a `GEN_*` constant and `value` must be an object of the +// corresponding type. `gen` takes ownership of `value`, so `value` must have // been an allocated object. // -// WARNING: |gen| must be empty (typically as returned from |GENERAL_NAME_new|) -// before calling this function. If |gen| already contained a value, the +// WARNING: `gen` must be empty (typically as returned from `GENERAL_NAME_new`) +// before calling this function. If `gen` already contained a value, the // previous contents will be leaked. OPENSSL_EXPORT void GENERAL_NAME_set0_value(GENERAL_NAME *gen, int type, void *value); -// GENERAL_NAME_get0_value returns the in-memory representation of |gen|'s -// contents and, |out_type| is not NULL, sets |*out_type| to the type of |gen|, -// which will be a |GEN_*| constant. If |gen| is incomplete, the return value +// GENERAL_NAME_get0_value returns the in-memory representation of `gen`'s +// contents and, `out_type` is not NULL, sets `*out_type` to the type of `gen`, +// which will be a `GEN_*` constant. If `gen` is incomplete, the return value // will be NULL and the type will be -1. // // WARNING: Casting the result of this function to the wrong type is a -// potentially exploitable memory error. Callers must check |gen|'s type, either -// via |*out_type| or checking |gen->type| directly, before inspecting the +// potentially exploitable memory error. Callers must check `gen`'s type, either +// via `*out_type` or checking `gen->type` directly, before inspecting the // result. // // WARNING: This function is not const-correct. The return value should be @@ -2136,27 +2136,27 @@ OPENSSL_EXPORT void *GENERAL_NAME_get0_value(const GENERAL_NAME *gen, int *out_type); -// GENERAL_NAME_set0_othername sets |gen| to be an OtherName with type |oid| and -// value |value|. On success, it returns one and takes ownership of |oid| and -// |value|, which must be created in a way compatible with |ASN1_OBJECT_free| -// and |ASN1_TYPE_free|, respectively. On allocation failure, it returns zero. -// In the failure case, the caller retains ownership of |oid| and |value| and +// GENERAL_NAME_set0_othername sets `gen` to be an OtherName with type `oid` and +// value `value`. On success, it returns one and takes ownership of `oid` and +// `value`, which must be created in a way compatible with `ASN1_OBJECT_free` +// and `ASN1_TYPE_free`, respectively. On allocation failure, it returns zero. +// In the failure case, the caller retains ownership of `oid` and `value` and // must release them when done. // -// WARNING: |gen| must be empty (typically as returned from |GENERAL_NAME_new|) -// before calling this function. If |gen| already contained a value, the +// WARNING: `gen` must be empty (typically as returned from `GENERAL_NAME_new`) +// before calling this function. If `gen` already contained a value, the // previously contents will be leaked. OPENSSL_EXPORT int GENERAL_NAME_set0_othername(GENERAL_NAME *gen, ASN1_OBJECT *oid, ASN1_TYPE *value); -// GENERAL_NAME_get0_otherName, if |gen| is an OtherName, sets |*out_oid| and -// |*out_value| to the OtherName's type-id and value, respectively, and returns -// one. If |gen| is not an OtherName, it returns zero and leaves |*out_oid| and -// |*out_value| unmodified. Either of |out_oid| or |out_value| may be NULL to +// GENERAL_NAME_get0_otherName, if `gen` is an OtherName, sets `*out_oid` and +// `*out_value` to the OtherName's type-id and value, respectively, and returns +// one. If `gen` is not an OtherName, it returns zero and leaves `*out_oid` and +// `*out_value` unmodified. Either of `out_oid` or `out_value` may be NULL to // ignore the value. // -// WARNING: This function is not const-correct. |out_oid| and |out_value| are +// WARNING: This function is not const-correct. `out_oid` and `out_value` are // not const, but callers should not mutate the resulting objects. OPENSSL_EXPORT int GENERAL_NAME_get0_otherName(const GENERAL_NAME *gen, ASN1_OBJECT **out_oid, @@ -2167,10 +2167,10 @@ // // The authority key identifier extension (RFC 5280, section 4.2.1.1) allows a // certificate to more precisely identify its issuer. This is helpful when -// multiple certificates share a name. Only the keyIdentifier (|keyid| in -// |AUTHORITY_KEYID|) field is used in practice. +// multiple certificates share a name. Only the keyIdentifier (`keyid` in +// `AUTHORITY_KEYID`) field is used in practice. -// A AUTHORITY_KEYID_st, aka |AUTHORITY_KEYID|, represents an +// A AUTHORITY_KEYID_st, aka `AUTHORITY_KEYID`, represents an // AuthorityKeyIdentifier structure (RFC 5280). struct AUTHORITY_KEYID_st { ASN1_OCTET_STRING *keyid; @@ -2178,25 +2178,25 @@ ASN1_INTEGER *serial; } /* AUTHORITY_KEYID */; -// AUTHORITY_KEYID is an |ASN1_ITEM| whose ASN.1 type is AuthorityKeyIdentifier -// (RFC 5280) and C type is |AUTHORITY_KEYID*|. +// AUTHORITY_KEYID is an `ASN1_ITEM` whose ASN.1 type is AuthorityKeyIdentifier +// (RFC 5280) and C type is `AUTHORITY_KEYID*`. DECLARE_ASN1_ITEM(AUTHORITY_KEYID) -// AUTHORITY_KEYID_new returns a newly-allocated, empty |AUTHORITY_KEYID| +// AUTHORITY_KEYID_new returns a newly-allocated, empty `AUTHORITY_KEYID` // object, or NULL on error. OPENSSL_EXPORT AUTHORITY_KEYID *AUTHORITY_KEYID_new(void); -// AUTHORITY_KEYID_free releases memory associated with |akid|. +// AUTHORITY_KEYID_free releases memory associated with `akid`. OPENSSL_EXPORT void AUTHORITY_KEYID_free(AUTHORITY_KEYID *akid); -// d2i_AUTHORITY_KEYID parses up to |len| bytes from |*inp| as a DER-encoded -// AuthorityKeyIdentifier (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_AUTHORITY_KEYID parses up to `len` bytes from `*inp` as a DER-encoded +// AuthorityKeyIdentifier (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT AUTHORITY_KEYID *d2i_AUTHORITY_KEYID(AUTHORITY_KEYID **out, const uint8_t **inp, long len); -// i2d_AUTHORITY_KEYID marshals |akid| as a DER-encoded AuthorityKeyIdentifier -// (RFC 5280), as described in |i2d_SAMPLE|. +// i2d_AUTHORITY_KEYID marshals `akid` as a DER-encoded AuthorityKeyIdentifier +// (RFC 5280), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_AUTHORITY_KEYID(const AUTHORITY_KEYID *akid, uint8_t **outp); @@ -2217,29 +2217,29 @@ DEFINE_STACK_OF(GENERAL_SUBTREE) -// GENERAL_SUBTREE_new returns a newly-allocated, empty |GENERAL_SUBTREE| +// GENERAL_SUBTREE_new returns a newly-allocated, empty `GENERAL_SUBTREE` // object, or NULL on error. OPENSSL_EXPORT GENERAL_SUBTREE *GENERAL_SUBTREE_new(void); -// GENERAL_SUBTREE_free releases memory associated with |subtree|. +// GENERAL_SUBTREE_free releases memory associated with `subtree`. OPENSSL_EXPORT void GENERAL_SUBTREE_free(GENERAL_SUBTREE *subtree); -// A NAME_CONSTRAINTS_st, aka |NAME_CONSTRAINTS|, represents a NameConstraints +// A NAME_CONSTRAINTS_st, aka `NAME_CONSTRAINTS`, represents a NameConstraints // structure (RFC 5280). struct NAME_CONSTRAINTS_st { STACK_OF(GENERAL_SUBTREE) *permittedSubtrees; STACK_OF(GENERAL_SUBTREE) *excludedSubtrees; } /* NAME_CONSTRAINTS */; -// NAME_CONSTRAINTS is an |ASN1_ITEM| whose ASN.1 type is NameConstraints (RFC -// 5280) and C type is |NAME_CONSTRAINTS*|. +// NAME_CONSTRAINTS is an `ASN1_ITEM` whose ASN.1 type is NameConstraints (RFC +// 5280) and C type is `NAME_CONSTRAINTS*`. DECLARE_ASN1_ITEM(NAME_CONSTRAINTS) -// NAME_CONSTRAINTS_new returns a newly-allocated, empty |NAME_CONSTRAINTS| +// NAME_CONSTRAINTS_new returns a newly-allocated, empty `NAME_CONSTRAINTS` // object, or NULL on error. OPENSSL_EXPORT NAME_CONSTRAINTS *NAME_CONSTRAINTS_new(void); -// NAME_CONSTRAINTS_free releases memory associated with |ncons|. +// NAME_CONSTRAINTS_free releases memory associated with `ncons`. OPENSSL_EXPORT void NAME_CONSTRAINTS_free(NAME_CONSTRAINTS *ncons); @@ -2259,35 +2259,35 @@ DEFINE_STACK_OF(ACCESS_DESCRIPTION) -// ACCESS_DESCRIPTION_new returns a newly-allocated, empty |ACCESS_DESCRIPTION| +// ACCESS_DESCRIPTION_new returns a newly-allocated, empty `ACCESS_DESCRIPTION` // object, or NULL on error. OPENSSL_EXPORT ACCESS_DESCRIPTION *ACCESS_DESCRIPTION_new(void); -// ACCESS_DESCRIPTION_free releases memory associated with |desc|. +// ACCESS_DESCRIPTION_free releases memory associated with `desc`. OPENSSL_EXPORT void ACCESS_DESCRIPTION_free(ACCESS_DESCRIPTION *desc); typedef STACK_OF(ACCESS_DESCRIPTION) AUTHORITY_INFO_ACCESS; -// AUTHORITY_INFO_ACCESS is an |ASN1_ITEM| whose ASN.1 type is +// AUTHORITY_INFO_ACCESS is an `ASN1_ITEM` whose ASN.1 type is // AuthorityInfoAccessSyntax (RFC 5280) and C type is -// |STACK_OF(ACCESS_DESCRIPTION)*|, or |AUTHORITY_INFO_ACCESS*|. +// `STACK_OF(ACCESS_DESCRIPTION)*`, or `AUTHORITY_INFO_ACCESS*`. DECLARE_ASN1_ITEM(AUTHORITY_INFO_ACCESS) // AUTHORITY_INFO_ACCESS_new returns a newly-allocated, empty -// |AUTHORITY_INFO_ACCESS| object, or NULL on error. +// `AUTHORITY_INFO_ACCESS` object, or NULL on error. OPENSSL_EXPORT AUTHORITY_INFO_ACCESS *AUTHORITY_INFO_ACCESS_new(void); -// AUTHORITY_INFO_ACCESS_free releases memory associated with |aia|. +// AUTHORITY_INFO_ACCESS_free releases memory associated with `aia`. OPENSSL_EXPORT void AUTHORITY_INFO_ACCESS_free(AUTHORITY_INFO_ACCESS *aia); -// d2i_AUTHORITY_INFO_ACCESS parses up to |len| bytes from |*inp| as a +// d2i_AUTHORITY_INFO_ACCESS parses up to `len` bytes from `*inp` as a // DER-encoded AuthorityInfoAccessSyntax (RFC 5280), as described in -// |d2i_SAMPLE|. +// `d2i_SAMPLE`. OPENSSL_EXPORT AUTHORITY_INFO_ACCESS *d2i_AUTHORITY_INFO_ACCESS( AUTHORITY_INFO_ACCESS **out, const uint8_t **inp, long len); -// i2d_AUTHORITY_INFO_ACCESS marshals |aia| as a DER-encoded -// AuthorityInfoAccessSyntax (RFC 5280), as described in |i2d_SAMPLE|. +// i2d_AUTHORITY_INFO_ACCESS marshals `aia` as a DER-encoded +// AuthorityInfoAccessSyntax (RFC 5280), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_AUTHORITY_INFO_ACCESS(const AUTHORITY_INFO_ACCESS *aia, uint8_t **outp); @@ -2299,11 +2299,11 @@ // point CRL extension (RFC 5280, section 5.2.5) matches against this extension. // A DIST_POINT_NAME represents a DistributionPointName structure (RFC 5280). -// The |name| field contains the CHOICE value and is determined by |type|. If -// |type| is zero, |name| must be a |fullname|. If |type| is one, |name| must be -// a |relativename|. +// The `name` field contains the CHOICE value and is determined by `type`. If +// `type` is zero, `name` must be a `fullname`. If `type` is one, `name` must be +// a `relativename`. // -// WARNING: |type| and |name| must be kept consistent. An inconsistency will +// WARNING: `type` and `name` must be kept consistent. An inconsistency will // result in a potentially exploitable memory error. typedef struct DIST_POINT_NAME_st { int type; @@ -2315,14 +2315,14 @@ X509_NAME *dpname; } DIST_POINT_NAME; -// DIST_POINT_NAME_new returns a newly-allocated, empty |DIST_POINT_NAME| +// DIST_POINT_NAME_new returns a newly-allocated, empty `DIST_POINT_NAME` // object, or NULL on error. OPENSSL_EXPORT DIST_POINT_NAME *DIST_POINT_NAME_new(void); -// DIST_POINT_NAME_free releases memory associated with |name|. +// DIST_POINT_NAME_free releases memory associated with `name`. OPENSSL_EXPORT void DIST_POINT_NAME_free(DIST_POINT_NAME *name); -// A DIST_POINT_st, aka |DIST_POINT|, represents a DistributionPoint structure +// A DIST_POINT_st, aka `DIST_POINT`, represents a DistributionPoint structure // (RFC 5280). struct DIST_POINT_st { DIST_POINT_NAME *distpoint; @@ -2332,38 +2332,38 @@ DEFINE_STACK_OF(DIST_POINT) -// DIST_POINT_new returns a newly-allocated, empty |DIST_POINT| object, or NULL +// DIST_POINT_new returns a newly-allocated, empty `DIST_POINT` object, or NULL // on error. OPENSSL_EXPORT DIST_POINT *DIST_POINT_new(void); -// DIST_POINT_free releases memory associated with |dp|. +// DIST_POINT_free releases memory associated with `dp`. OPENSSL_EXPORT void DIST_POINT_free(DIST_POINT *dp); typedef STACK_OF(DIST_POINT) CRL_DIST_POINTS; -// CRL_DIST_POINTS is an |ASN1_ITEM| whose ASN.1 type is CRLDistributionPoints -// (RFC 5280) and C type is |CRL_DIST_POINTS*|. +// CRL_DIST_POINTS is an `ASN1_ITEM` whose ASN.1 type is CRLDistributionPoints +// (RFC 5280) and C type is `CRL_DIST_POINTS*`. DECLARE_ASN1_ITEM(CRL_DIST_POINTS) -// CRL_DIST_POINTS_new returns a newly-allocated, empty |CRL_DIST_POINTS| +// CRL_DIST_POINTS_new returns a newly-allocated, empty `CRL_DIST_POINTS` // object, or NULL on error. OPENSSL_EXPORT CRL_DIST_POINTS *CRL_DIST_POINTS_new(void); -// CRL_DIST_POINTS_free releases memory associated with |crldp|. +// CRL_DIST_POINTS_free releases memory associated with `crldp`. OPENSSL_EXPORT void CRL_DIST_POINTS_free(CRL_DIST_POINTS *crldp); -// d2i_CRL_DIST_POINTS parses up to |len| bytes from |*inp| as a DER-encoded -// CRLDistributionPoints (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_CRL_DIST_POINTS parses up to `len` bytes from `*inp` as a DER-encoded +// CRLDistributionPoints (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT CRL_DIST_POINTS *d2i_CRL_DIST_POINTS(CRL_DIST_POINTS **out, const uint8_t **inp, long len); -// i2d_CRL_DIST_POINTS marshals |crldp| as a DER-encoded CRLDistributionPoints -// (RFC 5280), as described in |i2d_SAMPLE|. +// i2d_CRL_DIST_POINTS marshals `crldp` as a DER-encoded CRLDistributionPoints +// (RFC 5280), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_CRL_DIST_POINTS(const CRL_DIST_POINTS *crldp, uint8_t **outp); -// A ISSUING_DIST_POINT_st, aka |ISSUING_DIST_POINT|, represents a +// A ISSUING_DIST_POINT_st, aka `ISSUING_DIST_POINT`, represents a // IssuingDistributionPoint structure (RFC 5280). struct ISSUING_DIST_POINT_st { DIST_POINT_NAME *distpoint; @@ -2374,24 +2374,24 @@ ASN1_BOOLEAN onlyattr; } /* ISSUING_DIST_POINT */; -// ISSUING_DIST_POINT is an |ASN1_ITEM| whose ASN.1 type is -// IssuingDistributionPoint (RFC 5280) and C type is |ISSUING_DIST_POINT*|. +// ISSUING_DIST_POINT is an `ASN1_ITEM` whose ASN.1 type is +// IssuingDistributionPoint (RFC 5280) and C type is `ISSUING_DIST_POINT*`. DECLARE_ASN1_ITEM(ISSUING_DIST_POINT) -// ISSUING_DIST_POINT_new returns a newly-allocated, empty |ISSUING_DIST_POINT| +// ISSUING_DIST_POINT_new returns a newly-allocated, empty `ISSUING_DIST_POINT` // object, or NULL on error. OPENSSL_EXPORT ISSUING_DIST_POINT *ISSUING_DIST_POINT_new(void); -// ISSUING_DIST_POINT_free releases memory associated with |idp|. +// ISSUING_DIST_POINT_free releases memory associated with `idp`. OPENSSL_EXPORT void ISSUING_DIST_POINT_free(ISSUING_DIST_POINT *idp); -// d2i_ISSUING_DIST_POINT parses up to |len| bytes from |*inp| as a DER-encoded -// IssuingDistributionPoint (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_ISSUING_DIST_POINT parses up to `len` bytes from `*inp` as a DER-encoded +// IssuingDistributionPoint (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT ISSUING_DIST_POINT *d2i_ISSUING_DIST_POINT( ISSUING_DIST_POINT **out, const uint8_t **inp, long len); -// i2d_ISSUING_DIST_POINT marshals |idp| as a DER-encoded -// IssuingDistributionPoint (RFC 5280), as described in |i2d_SAMPLE|. +// i2d_ISSUING_DIST_POINT marshals `idp` as a DER-encoded +// IssuingDistributionPoint (RFC 5280), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_ISSUING_DIST_POINT(const ISSUING_DIST_POINT *idp, uint8_t **outp); @@ -2412,11 +2412,11 @@ STACK_OF(ASN1_INTEGER) *noticenos; } NOTICEREF; -// NOTICEREF_new returns a newly-allocated, empty |NOTICEREF| object, or NULL +// NOTICEREF_new returns a newly-allocated, empty `NOTICEREF` object, or NULL // on error. OPENSSL_EXPORT NOTICEREF *NOTICEREF_new(void); -// NOTICEREF_free releases memory associated with |ref|. +// NOTICEREF_free releases memory associated with `ref`. OPENSSL_EXPORT void NOTICEREF_free(NOTICEREF *ref); // A USERNOTICE represents a UserNotice structure (RFC 5280). @@ -2425,20 +2425,20 @@ ASN1_STRING *exptext; } USERNOTICE; -// USERNOTICE_new returns a newly-allocated, empty |USERNOTICE| object, or NULL +// USERNOTICE_new returns a newly-allocated, empty `USERNOTICE` object, or NULL // on error. OPENSSL_EXPORT USERNOTICE *USERNOTICE_new(void); -// USERNOTICE_free releases memory associated with |notice|. +// USERNOTICE_free releases memory associated with `notice`. OPENSSL_EXPORT void USERNOTICE_free(USERNOTICE *notice); -// A POLICYQUALINFO represents a PolicyQualifierInfo structure (RFC 5280). |d| +// A POLICYQUALINFO represents a PolicyQualifierInfo structure (RFC 5280). `d` // contains the qualifier field of the PolicyQualifierInfo. Its type is -// determined by |pqualid|. If |pqualid| is |NID_id_qt_cps|, |d| must be -// |cpsuri|. If |pqualid| is |NID_id_qt_unotice|, |d| must be |usernotice|. -// Otherwise, |d| must be |other|. +// determined by `pqualid`. If `pqualid` is `NID_id_qt_cps`, `d` must be +// `cpsuri`. If `pqualid` is `NID_id_qt_unotice`, `d` must be `usernotice`. +// Otherwise, `d` must be `other`. // -// WARNING: |pqualid| and |d| must be kept consistent. An inconsistency will +// WARNING: `pqualid` and `d` must be kept consistent. An inconsistency will // result in a potentially exploitable memory error. typedef struct POLICYQUALINFO_st { ASN1_OBJECT *pqualid; @@ -2451,11 +2451,11 @@ DEFINE_STACK_OF(POLICYQUALINFO) -// POLICYQUALINFO_new returns a newly-allocated, empty |POLICYQUALINFO| object, +// POLICYQUALINFO_new returns a newly-allocated, empty `POLICYQUALINFO` object, // or NULL on error. OPENSSL_EXPORT POLICYQUALINFO *POLICYQUALINFO_new(void); -// POLICYQUALINFO_free releases memory associated with |info|. +// POLICYQUALINFO_free releases memory associated with `info`. OPENSSL_EXPORT void POLICYQUALINFO_free(POLICYQUALINFO *info); // A POLICYINFO represents a PolicyInformation structure (RFC 5280). @@ -2466,33 +2466,33 @@ DEFINE_STACK_OF(POLICYINFO) -// POLICYINFO_new returns a newly-allocated, empty |POLICYINFO| object, or NULL +// POLICYINFO_new returns a newly-allocated, empty `POLICYINFO` object, or NULL // on error. OPENSSL_EXPORT POLICYINFO *POLICYINFO_new(void); -// POLICYINFO_free releases memory associated with |info|. +// POLICYINFO_free releases memory associated with `info`. OPENSSL_EXPORT void POLICYINFO_free(POLICYINFO *info); typedef STACK_OF(POLICYINFO) CERTIFICATEPOLICIES; -// CERTIFICATEPOLICIES is an |ASN1_ITEM| whose ASN.1 type is CertificatePolicies -// (RFC 5280) and C type is |STACK_OF(POLICYINFO)*|, or |CERTIFICATEPOLICIES*|. +// CERTIFICATEPOLICIES is an `ASN1_ITEM` whose ASN.1 type is CertificatePolicies +// (RFC 5280) and C type is `STACK_OF(POLICYINFO)*`, or `CERTIFICATEPOLICIES*`. DECLARE_ASN1_ITEM(CERTIFICATEPOLICIES) // CERTIFICATEPOLICIES_new returns a newly-allocated, empty -// |CERTIFICATEPOLICIES| object, or NULL on error. +// `CERTIFICATEPOLICIES` object, or NULL on error. OPENSSL_EXPORT CERTIFICATEPOLICIES *CERTIFICATEPOLICIES_new(void); -// CERTIFICATEPOLICIES_free releases memory associated with |policies|. +// CERTIFICATEPOLICIES_free releases memory associated with `policies`. OPENSSL_EXPORT void CERTIFICATEPOLICIES_free(CERTIFICATEPOLICIES *policies); -// d2i_CERTIFICATEPOLICIES parses up to |len| bytes from |*inp| as a DER-encoded -// CertificatePolicies (RFC 5280), as described in |d2i_SAMPLE|. +// d2i_CERTIFICATEPOLICIES parses up to `len` bytes from `*inp` as a DER-encoded +// CertificatePolicies (RFC 5280), as described in `d2i_SAMPLE`. OPENSSL_EXPORT CERTIFICATEPOLICIES *d2i_CERTIFICATEPOLICIES( CERTIFICATEPOLICIES **out, const uint8_t **inp, long len); -// i2d_CERTIFICATEPOLICIES marshals |policies| as a DER-encoded -// CertificatePolicies (RFC 5280), as described in |i2d_SAMPLE|. +// i2d_CERTIFICATEPOLICIES marshals `policies` as a DER-encoded +// CertificatePolicies (RFC 5280), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_CERTIFICATEPOLICIES(const CERTIFICATEPOLICIES *policies, uint8_t **outp); @@ -2505,17 +2505,17 @@ DEFINE_STACK_OF(POLICY_MAPPING) -// POLICY_MAPPING_new returns a newly-allocated, empty |POLICY_MAPPING| object, +// POLICY_MAPPING_new returns a newly-allocated, empty `POLICY_MAPPING` object, // or NULL on error. OPENSSL_EXPORT POLICY_MAPPING *POLICY_MAPPING_new(void); -// POLICY_MAPPING_free releases memory associated with |mapping|. +// POLICY_MAPPING_free releases memory associated with `mapping`. OPENSSL_EXPORT void POLICY_MAPPING_free(POLICY_MAPPING *mapping); typedef STACK_OF(POLICY_MAPPING) POLICY_MAPPINGS; -// POLICY_MAPPINGS is an |ASN1_ITEM| whose ASN.1 type is PolicyMappings (RFC -// 5280) and C type is |STACK_OF(POLICY_MAPPING)*|, or |POLICY_MAPPINGS*|. +// POLICY_MAPPINGS is an `ASN1_ITEM` whose ASN.1 type is PolicyMappings (RFC +// 5280) and C type is `STACK_OF(POLICY_MAPPING)*`, or `POLICY_MAPPINGS*`. DECLARE_ASN1_ITEM(POLICY_MAPPINGS) // A POLICY_CONSTRAINTS represents a PolicyConstraints structure (RFC 5280). @@ -2524,96 +2524,96 @@ ASN1_INTEGER *inhibitPolicyMapping; } POLICY_CONSTRAINTS; -// POLICY_CONSTRAINTS is an |ASN1_ITEM| whose ASN.1 type is PolicyConstraints -// (RFC 5280) and C type is |POLICY_CONSTRAINTS*|. +// POLICY_CONSTRAINTS is an `ASN1_ITEM` whose ASN.1 type is PolicyConstraints +// (RFC 5280) and C type is `POLICY_CONSTRAINTS*`. DECLARE_ASN1_ITEM(POLICY_CONSTRAINTS) -// POLICY_CONSTRAINTS_new returns a newly-allocated, empty |POLICY_CONSTRAINTS| +// POLICY_CONSTRAINTS_new returns a newly-allocated, empty `POLICY_CONSTRAINTS` // object, or NULL on error. OPENSSL_EXPORT POLICY_CONSTRAINTS *POLICY_CONSTRAINTS_new(void); -// POLICY_CONSTRAINTS_free releases memory associated with |pcons|. +// POLICY_CONSTRAINTS_free releases memory associated with `pcons`. OPENSSL_EXPORT void POLICY_CONSTRAINTS_free(POLICY_CONSTRAINTS *pcons); // Algorithm identifiers. // -// An |X509_ALGOR| represents an AlgorithmIdentifier structure, used in X.509 +// An `X509_ALGOR` represents an AlgorithmIdentifier structure, used in X.509 // to represent signature algorithms and public key algorithms. DEFINE_STACK_OF(X509_ALGOR) -// X509_ALGOR is an |ASN1_ITEM| whose ASN.1 type is AlgorithmIdentifier and C -// type is |X509_ALGOR*|. +// X509_ALGOR is an `ASN1_ITEM` whose ASN.1 type is AlgorithmIdentifier and C +// type is `X509_ALGOR*`. DECLARE_ASN1_ITEM(X509_ALGOR) -// X509_ALGOR_new returns a newly-allocated, empty |X509_ALGOR| object, or NULL +// X509_ALGOR_new returns a newly-allocated, empty `X509_ALGOR` object, or NULL // on error. OPENSSL_EXPORT X509_ALGOR *X509_ALGOR_new(void); -// X509_ALGOR_dup returns a newly-allocated copy of |alg|, or NULL on error. -// This function works by serializing the structure, so if |alg| is incomplete, +// X509_ALGOR_dup returns a newly-allocated copy of `alg`, or NULL on error. +// This function works by serializing the structure, so if `alg` is incomplete, // it may fail. OPENSSL_EXPORT X509_ALGOR *X509_ALGOR_dup(const X509_ALGOR *alg); -// X509_ALGOR_copy sets |dst| to a copy of the contents of |src|. It returns one +// X509_ALGOR_copy sets `dst` to a copy of the contents of `src`. It returns one // on success and zero on error. OPENSSL_EXPORT int X509_ALGOR_copy(X509_ALGOR *dst, const X509_ALGOR *src); -// X509_ALGOR_free releases memory associated with |alg|. +// X509_ALGOR_free releases memory associated with `alg`. OPENSSL_EXPORT void X509_ALGOR_free(X509_ALGOR *alg); -// d2i_X509_ALGOR parses up to |len| bytes from |*inp| as a DER-encoded -// AlgorithmIdentifier, as described in |d2i_SAMPLE|. +// d2i_X509_ALGOR parses up to `len` bytes from `*inp` as a DER-encoded +// AlgorithmIdentifier, as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509_ALGOR *d2i_X509_ALGOR(X509_ALGOR **out, const uint8_t **inp, long len); -// i2d_X509_ALGOR marshals |alg| as a DER-encoded AlgorithmIdentifier, as -// described in |i2d_SAMPLE|. +// i2d_X509_ALGOR marshals `alg` as a DER-encoded AlgorithmIdentifier, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509_ALGOR(const X509_ALGOR *alg, uint8_t **outp); -// X509_ALGOR_set0 sets |alg| to an AlgorithmIdentifier with algorithm |obj| and -// parameter determined by |param_type| and |param_value|. It returns one on -// success and zero on error. This function takes ownership of |obj| and -// |param_value| on success. +// X509_ALGOR_set0 sets `alg` to an AlgorithmIdentifier with algorithm `obj` and +// parameter determined by `param_type` and `param_value`. It returns one on +// success and zero on error. This function takes ownership of `obj` and +// `param_value` on success. // -// If |param_type| is |V_ASN1_UNDEF|, the parameter is omitted. If |param_type| -// is zero, the parameter is left unchanged. Otherwise, |param_type| and -// |param_value| are interpreted as in |ASN1_TYPE_set|. +// If `param_type` is `V_ASN1_UNDEF`, the parameter is omitted. If `param_type` +// is zero, the parameter is left unchanged. Otherwise, `param_type` and +// `param_value` are interpreted as in `ASN1_TYPE_set`. // -// Note omitting the parameter (|V_ASN1_UNDEF|) and encoding an explicit NULL -// value (|V_ASN1_NULL|) are different. Some algorithms require one and some the +// Note omitting the parameter (`V_ASN1_UNDEF`) and encoding an explicit NULL +// value (`V_ASN1_NULL`) are different. Some algorithms require one and some the // other. Consult the relevant specification before calling this function. The -// correct parameter for an RSASSA-PKCS1-v1_5 signature is |V_ASN1_NULL|. The -// correct one for an ECDSA or Ed25519 signature is |V_ASN1_UNDEF|. +// correct parameter for an RSASSA-PKCS1-v1_5 signature is `V_ASN1_NULL`. The +// correct one for an ECDSA or Ed25519 signature is `V_ASN1_UNDEF`. OPENSSL_EXPORT int X509_ALGOR_set0(X509_ALGOR *alg, ASN1_OBJECT *obj, int param_type, void *param_value); -// X509_ALGOR_get0 sets |*out_obj| to the |alg|'s algorithm. If |alg|'s -// parameter is omitted, it sets |*out_param_type| and |*out_param_value| to -// |V_ASN1_UNDEF| and NULL. Otherwise, it sets |*out_param_type| and -// |*out_param_value| to the parameter, using the same representation as -// |ASN1_TYPE_set0|. See |ASN1_TYPE_set0| and |ASN1_TYPE| for details. +// X509_ALGOR_get0 sets `*out_obj` to the `alg`'s algorithm. If `alg`'s +// parameter is omitted, it sets `*out_param_type` and `*out_param_value` to +// `V_ASN1_UNDEF` and NULL. Otherwise, it sets `*out_param_type` and +// `*out_param_value` to the parameter, using the same representation as +// `ASN1_TYPE_set0`. See `ASN1_TYPE_set0` and `ASN1_TYPE` for details. // // Callers that require the parameter in serialized form should, after checking -// for |V_ASN1_UNDEF|, use |ASN1_TYPE_set1| and |d2i_ASN1_TYPE|, rather than -// inspecting |*out_param_value|. +// for `V_ASN1_UNDEF`, use `ASN1_TYPE_set1` and `d2i_ASN1_TYPE`, rather than +// inspecting `*out_param_value`. // -// Each of |out_obj|, |out_param_type|, and |out_param_value| may be NULL to -// ignore the output. If |out_param_type| is NULL, |out_param_value| is ignored. +// Each of `out_obj`, `out_param_type`, and `out_param_value` may be NULL to +// ignore the output. If `out_param_type` is NULL, `out_param_value` is ignored. // -// WARNING: If |*out_param_type| is set to |V_ASN1_UNDEF|, OpenSSL and older -// revisions of BoringSSL leave |*out_param_value| unset rather than setting it +// WARNING: If `*out_param_type` is set to `V_ASN1_UNDEF`, OpenSSL and older +// revisions of BoringSSL leave `*out_param_value` unset rather than setting it // to NULL. Callers that support both OpenSSL and BoringSSL should not assume -// |*out_param_value| is uniformly initialized. +// `*out_param_value` is uniformly initialized. OPENSSL_EXPORT void X509_ALGOR_get0(const ASN1_OBJECT **out_obj, int *out_param_type, const void **out_param_value, const X509_ALGOR *alg); -// X509_ALGOR_set_md sets |alg| to the hash function |md|. Note this +// X509_ALGOR_set_md sets `alg` to the hash function `md`. Note this // AlgorithmIdentifier represents the hash function itself, not a signature -// algorithm that uses |md|. It returns one on success and zero on error. +// algorithm that uses `md`. It returns one on success and zero on error. // // Due to historical specification mistakes (see Section 2.1 of RFC 4055), the // parameters field is sometimes omitted and sometimes a NULL value. When used @@ -2626,7 +2626,7 @@ // constructing PSS and move on. OPENSSL_EXPORT int X509_ALGOR_set_md(X509_ALGOR *alg, const EVP_MD *md); -// X509_ALGOR_cmp returns zero if |a| and |b| are equal, and some non-zero value +// X509_ALGOR_cmp returns zero if `a` and `b` are equal, and some non-zero value // otherwise. Note this function can only be used for equality checks, not an // ordering. OPENSSL_EXPORT int X509_ALGOR_cmp(const X509_ALGOR *a, const X509_ALGOR *b); @@ -2636,51 +2636,51 @@ // // Unlike certificates and CRLs, CSRs use a separate Attribute structure (RFC // 2985, RFC 2986) for extensibility. This is represented by the library as -// |X509_ATTRIBUTE|. +// `X509_ATTRIBUTE`. DEFINE_STACK_OF(X509_ATTRIBUTE) -// X509_ATTRIBUTE_new returns a newly-allocated, empty |X509_ATTRIBUTE| object, -// or NULL on error. |X509_ATTRIBUTE_set1_*| may be used to finish initializing +// X509_ATTRIBUTE_new returns a newly-allocated, empty `X509_ATTRIBUTE` object, +// or NULL on error. `X509_ATTRIBUTE_set1_*` may be used to finish initializing // it. OPENSSL_EXPORT X509_ATTRIBUTE *X509_ATTRIBUTE_new(void); -// X509_ATTRIBUTE_dup returns a newly-allocated copy of |attr|, or NULL on -// error. This function works by serializing the structure, so if |attr| is +// X509_ATTRIBUTE_dup returns a newly-allocated copy of `attr`, or NULL on +// error. This function works by serializing the structure, so if `attr` is // incomplete, it may fail. OPENSSL_EXPORT X509_ATTRIBUTE *X509_ATTRIBUTE_dup(const X509_ATTRIBUTE *attr); -// X509_ATTRIBUTE_free releases memory associated with |attr|. +// X509_ATTRIBUTE_free releases memory associated with `attr`. OPENSSL_EXPORT void X509_ATTRIBUTE_free(X509_ATTRIBUTE *attr); -// d2i_X509_ATTRIBUTE parses up to |len| bytes from |*inp| as a DER-encoded -// Attribute (RFC 2986), as described in |d2i_SAMPLE|. +// d2i_X509_ATTRIBUTE parses up to `len` bytes from `*inp` as a DER-encoded +// Attribute (RFC 2986), as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509_ATTRIBUTE *d2i_X509_ATTRIBUTE(X509_ATTRIBUTE **out, const uint8_t **inp, long len); -// i2d_X509_ATTRIBUTE marshals |alg| as a DER-encoded Attribute (RFC 2986), as -// described in |i2d_SAMPLE|. +// i2d_X509_ATTRIBUTE marshals `alg` as a DER-encoded Attribute (RFC 2986), as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509_ATTRIBUTE(const X509_ATTRIBUTE *alg, uint8_t **outp); -// X509_ATTRIBUTE_create returns a newly-allocated |X509_ATTRIBUTE|, or NULL on -// error. The attribute has type |nid| and contains a single value determined by -// |attrtype| and |value|, which are interpreted as in |ASN1_TYPE_set|. Note -// this function takes ownership of |value|. +// X509_ATTRIBUTE_create returns a newly-allocated `X509_ATTRIBUTE`, or NULL on +// error. The attribute has type `nid` and contains a single value determined by +// `attrtype` and `value`, which are interpreted as in `ASN1_TYPE_set`. Note +// this function takes ownership of `value`. OPENSSL_EXPORT X509_ATTRIBUTE *X509_ATTRIBUTE_create(int nid, int attrtype, void *value); -// X509_ATTRIBUTE_create_by_NID returns a newly-allocated |X509_ATTRIBUTE| of -// type |nid|, or NULL on error. The value is determined as in -// |X509_ATTRIBUTE_set1_data|. +// X509_ATTRIBUTE_create_by_NID returns a newly-allocated `X509_ATTRIBUTE` of +// type `nid`, or NULL on error. The value is determined as in +// `X509_ATTRIBUTE_set1_data`. // -// If |attr| is non-NULL, the resulting |X509_ATTRIBUTE| is also written to -// |*attr|. If |*attr| was non-NULL when the function was called, |*attr| is +// If `attr` is non-NULL, the resulting `X509_ATTRIBUTE` is also written to +// `*attr`. If `*attr` was non-NULL when the function was called, `*attr` is // reused instead of creating a new object. // -// WARNING: The interpretation of |attrtype|, |data|, and |len| is complex and -// error-prone. See |X509_ATTRIBUTE_set1_data| for details. +// WARNING: The interpretation of `attrtype`, `data`, and `len` is complex and +// error-prone. See `X509_ATTRIBUTE_set1_data` for details. // // WARNING: The object reuse form is deprecated and may be removed in the // future. It also currently incorrectly appends to the reused object's value @@ -2688,201 +2688,201 @@ OPENSSL_EXPORT X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID( X509_ATTRIBUTE **attr, int nid, int attrtype, const void *data, int len); -// X509_ATTRIBUTE_create_by_OBJ behaves like |X509_ATTRIBUTE_create_by_NID| -// except the attribute's type is determined by |obj|. +// X509_ATTRIBUTE_create_by_OBJ behaves like `X509_ATTRIBUTE_create_by_NID` +// except the attribute's type is determined by `obj`. OPENSSL_EXPORT X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ( X509_ATTRIBUTE **attr, const ASN1_OBJECT *obj, int attrtype, const void *data, int len); -// X509_ATTRIBUTE_create_by_txt behaves like |X509_ATTRIBUTE_create_by_NID| -// except the attribute's type is determined by calling |OBJ_txt2obj| with -// |attrname|. +// X509_ATTRIBUTE_create_by_txt behaves like `X509_ATTRIBUTE_create_by_NID` +// except the attribute's type is determined by calling `OBJ_txt2obj` with +// `attrname`. OPENSSL_EXPORT X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_txt( X509_ATTRIBUTE **attr, const char *attrname, int type, const unsigned char *bytes, int len); -// X509_ATTRIBUTE_set1_object sets |attr|'s type to |obj|. It returns one on +// X509_ATTRIBUTE_set1_object sets `attr`'s type to `obj`. It returns one on // success and zero on error. OPENSSL_EXPORT int X509_ATTRIBUTE_set1_object(X509_ATTRIBUTE *attr, const ASN1_OBJECT *obj); -// X509_ATTRIBUTE_set1_data appends a value to |attr|'s value set and returns +// X509_ATTRIBUTE_set1_data appends a value to `attr`'s value set and returns // one on success or zero on error. The value is determined as follows: // -// If |attrtype| is zero, this function returns one and does nothing. This form -// may be used when calling |X509_ATTRIBUTE_create_by_*| to create an attribute +// If `attrtype` is zero, this function returns one and does nothing. This form +// may be used when calling `X509_ATTRIBUTE_create_by_*` to create an attribute // with an empty value set. Such attributes are invalid, but OpenSSL supports // creating them. // -// Otherwise, if |attrtype| is a |MBSTRING_*| constant, the value is an ASN.1 -// string. The string is determined by decoding |len| bytes from |data| in the -// encoding specified by |attrtype|, and then re-encoding it in a form -// appropriate for |attr|'s type. If |len| is -1, |strlen(data)| is used -// instead. See |ASN1_STRING_set_by_NID| for details. +// Otherwise, if `attrtype` is a `MBSTRING_*` constant, the value is an ASN.1 +// string. The string is determined by decoding `len` bytes from `data` in the +// encoding specified by `attrtype`, and then re-encoding it in a form +// appropriate for `attr`'s type. If `len` is -1, `strlen(data)` is used +// instead. See `ASN1_STRING_set_by_NID` for details. // -// Otherwise, if |len| is not -1, the value is an ASN.1 string. |attrtype| is an -// |ASN1_STRING| type value and the |len| bytes from |data| are copied as the -// type-specific representation of |ASN1_STRING|. See |ASN1_STRING| for details. +// Otherwise, if `len` is not -1, the value is an ASN.1 string. `attrtype` is an +// `ASN1_STRING` type value and the `len` bytes from `data` are copied as the +// type-specific representation of `ASN1_STRING`. See `ASN1_STRING` for details. // -// Otherwise, if |len| is -1, the value is constructed by passing |attrtype| and -// |data| to |ASN1_TYPE_set1|. That is, |attrtype| is an |ASN1_TYPE| type value, -// and |data| is cast to the corresponding pointer type. +// Otherwise, if `len` is -1, the value is constructed by passing `attrtype` and +// `data` to `ASN1_TYPE_set1`. That is, `attrtype` is an `ASN1_TYPE` type value, +// and `data` is cast to the corresponding pointer type. // -// WARNING: Despite the name, this function appends to |attr|'s value set, +// WARNING: Despite the name, this function appends to `attr`'s value set, // rather than overwriting it. To overwrite the value set, create a new -// |X509_ATTRIBUTE| with |X509_ATTRIBUTE_new|. +// `X509_ATTRIBUTE` with `X509_ATTRIBUTE_new`. // -// WARNING: If using the |MBSTRING_*| form, pass a length rather than relying on -// |strlen|. In particular, |strlen| will not behave correctly if the input is -// |MBSTRING_BMP| or |MBSTRING_UNIV|. +// WARNING: If using the `MBSTRING_*` form, pass a length rather than relying on +// `strlen`. In particular, `strlen` will not behave correctly if the input is +// `MBSTRING_BMP` or `MBSTRING_UNIV`. // -// WARNING: This function currently misinterprets |V_ASN1_OTHER| as an -// |MBSTRING_*| constant. This matches OpenSSL but means it is impossible to +// WARNING: This function currently misinterprets `V_ASN1_OTHER` as an +// `MBSTRING_*` constant. This matches OpenSSL but means it is impossible to // construct a value with a non-universal tag. OPENSSL_EXPORT int X509_ATTRIBUTE_set1_data(X509_ATTRIBUTE *attr, int attrtype, const void *data, int len); -// X509_ATTRIBUTE_get0_data returns the |idx|th value of |attr| in a -// type-specific representation to |attrtype|, or NULL if out of bounds or the -// type does not match. |attrtype| is one of the type values in |ASN1_TYPE|. On -// match, the return value uses the same representation as |ASN1_TYPE_set0|. See -// |ASN1_TYPE| for details. +// X509_ATTRIBUTE_get0_data returns the `idx`th value of `attr` in a +// type-specific representation to `attrtype`, or NULL if out of bounds or the +// type does not match. `attrtype` is one of the type values in `ASN1_TYPE`. On +// match, the return value uses the same representation as `ASN1_TYPE_set0`. See +// `ASN1_TYPE` for details. OPENSSL_EXPORT void *X509_ATTRIBUTE_get0_data(X509_ATTRIBUTE *attr, int idx, int attrtype, void *unused); -// X509_ATTRIBUTE_count returns the number of values in |attr|. +// X509_ATTRIBUTE_count returns the number of values in `attr`. OPENSSL_EXPORT int X509_ATTRIBUTE_count(const X509_ATTRIBUTE *attr); -// X509_ATTRIBUTE_get0_object returns the type of |attr|. +// X509_ATTRIBUTE_get0_object returns the type of `attr`. OPENSSL_EXPORT ASN1_OBJECT *X509_ATTRIBUTE_get0_object(X509_ATTRIBUTE *attr); -// X509_ATTRIBUTE_get0_type returns the |idx|th value in |attr|, or NULL if out -// of bounds. Note this function returns one of |attr|'s values, not the type. +// X509_ATTRIBUTE_get0_type returns the `idx`th value in `attr`, or NULL if out +// of bounds. Note this function returns one of `attr`'s values, not the type. OPENSSL_EXPORT ASN1_TYPE *X509_ATTRIBUTE_get0_type(X509_ATTRIBUTE *attr, int idx); // Certificate stores. // -// An |X509_STORE| contains trusted certificates, CRLs, and verification +// An `X509_STORE` contains trusted certificates, CRLs, and verification // parameters that are shared between multiple certificate verifications. // -// Certificates in an |X509_STORE| are referred to as "trusted certificates", +// Certificates in an `X509_STORE` are referred to as "trusted certificates", // but an individual certificate verification may not necessarily treat every -// trusted certificate as a trust anchor. See |X509_VERIFY_PARAM_set_trust| for +// trusted certificate as a trust anchor. See `X509_VERIFY_PARAM_set_trust` for // details. // // WARNING: Although a trusted certificate which fails the -// |X509_VERIFY_PARAM_set_trust| check is functionally an untrusted +// `X509_VERIFY_PARAM_set_trust` check is functionally an untrusted // intermediate certificate, callers should not rely on this to configure -// untrusted intermediates in an |X509_STORE|. The trust check is complex, so +// untrusted intermediates in an `X509_STORE`. The trust check is complex, so // this risks inadvertently treating it as a trust anchor. Instead, configure -// untrusted intermediates with the |chain| parameter of |X509_STORE_CTX_init|. +// untrusted intermediates with the `chain` parameter of `X509_STORE_CTX_init`. // -// Certificates in |X509_STORE| may be specified in several ways: -// - Added by |X509_STORE_add_cert|. -// - Returned by an |X509_LOOKUP| added by |X509_STORE_add_lookup|. +// Certificates in `X509_STORE` may be specified in several ways: +// - Added by `X509_STORE_add_cert`. +// - Returned by an `X509_LOOKUP` added by `X509_STORE_add_lookup`. // -// |X509_STORE|s are reference-counted and may be shared by certificate +// `X509_STORE`s are reference-counted and may be shared by certificate // verifications running concurrently on multiple threads. However, an -// |X509_STORE|'s verification parameters may not be modified concurrently with +// `X509_STORE`'s verification parameters may not be modified concurrently with // certificate verification or other operations. Unless otherwise documented, // functions which take const pointer may be used concurrently, while // functions which take a non-const pointer may not. Callers that wish to modify -// verification parameters in a shared |X509_STORE| should instead modify -// |X509_STORE_CTX|s individually. +// verification parameters in a shared `X509_STORE` should instead modify +// `X509_STORE_CTX`s individually. // -// Objects in an |X509_STORE| are represented as an |X509_OBJECT|. Some +// Objects in an `X509_STORE` are represented as an `X509_OBJECT`. Some // functions in this library return values with this type. -// X509_STORE_new returns a newly-allocated |X509_STORE|, or NULL on error. +// X509_STORE_new returns a newly-allocated `X509_STORE`, or NULL on error. OPENSSL_EXPORT X509_STORE *X509_STORE_new(void); -// X509_STORE_up_ref adds one to the reference count of |store| and returns one. -// Although |store| is not const, this function's use of |store| is thread-safe. +// X509_STORE_up_ref adds one to the reference count of `store` and returns one. +// Although `store` is not const, this function's use of `store` is thread-safe. OPENSSL_EXPORT int X509_STORE_up_ref(X509_STORE *store); -// X509_STORE_free releases memory associated with |store|. +// X509_STORE_free releases memory associated with `store`. OPENSSL_EXPORT void X509_STORE_free(X509_STORE *store); -// X509_STORE_add_cert adds |x509| to |store| as a trusted certificate. It +// X509_STORE_add_cert adds `x509` to `store` as a trusted certificate. It // returns one on success and zero on error. This function internally increments -// |x509|'s reference count, so the caller retains ownership of |x509|. +// `x509`'s reference count, so the caller retains ownership of `x509`. // // Certificates configured by this function are still subject to the checks -// described in |X509_VERIFY_PARAM_set_trust|. +// described in `X509_VERIFY_PARAM_set_trust`. // -// Although |store| is not const, this function's use of |store| is thread-safe. -// However, if this function is called concurrently with |X509_verify_cert|, it -// is a race condition whether |x509| is available for issuer lookups. +// Although `store` is not const, this function's use of `store` is thread-safe. +// However, if this function is called concurrently with `X509_verify_cert`, it +// is a race condition whether `x509` is available for issuer lookups. // Moreover, the result may differ for each issuer lookup performed by a single -// |X509_verify_cert| call. +// `X509_verify_cert` call. OPENSSL_EXPORT int X509_STORE_add_cert(X509_STORE *store, X509 *x509); -// X509_STORE_add_crl adds |crl| to |store|. It returns one on success and zero -// on error. This function internally increments |crl|'s reference count, so the -// caller retains ownership of |crl|. CRLs added in this way are candidates for -// CRL lookup when |X509_V_FLAG_CRL_CHECK| is set. +// X509_STORE_add_crl adds `crl` to `store`. It returns one on success and zero +// on error. This function internally increments `crl`'s reference count, so the +// caller retains ownership of `crl`. CRLs added in this way are candidates for +// CRL lookup when `X509_V_FLAG_CRL_CHECK` is set. // -// Although |store| is not const, this function's use of |store| is thread-safe. -// However, if this function is called concurrently with |X509_verify_cert|, it -// is a race condition whether |crl| is available for CRL checks. Moreover, the +// Although `store` is not const, this function's use of `store` is thread-safe. +// However, if this function is called concurrently with `X509_verify_cert`, it +// is a race condition whether `crl` is available for CRL checks. Moreover, the // result may differ for each CRL check performed by a single -// |X509_verify_cert| call. +// `X509_verify_cert` call. // -// Note there are no supported APIs to remove CRLs from |store| once inserted. +// Note there are no supported APIs to remove CRLs from `store` once inserted. // To vary the set of CRLs over time, callers should either create a new -// |X509_STORE| or configure CRLs on a per-verification basis with -// |X509_STORE_CTX_set0_crls|. +// `X509_STORE` or configure CRLs on a per-verification basis with +// `X509_STORE_CTX_set0_crls`. OPENSSL_EXPORT int X509_STORE_add_crl(X509_STORE *store, X509_CRL *crl); -// X509_STORE_get0_param returns |store|'s verification parameters. This object +// X509_STORE_get0_param returns `store`'s verification parameters. This object // is mutable and may be modified by the caller. For an individual certificate -// verification operation, |X509_STORE_CTX_init| initializes the -// |X509_STORE_CTX|'s parameters with these parameters. +// verification operation, `X509_STORE_CTX_init` initializes the +// `X509_STORE_CTX`'s parameters with these parameters. // -// WARNING: |X509_STORE_CTX_init| applies some default parameters (as in -// |X509_VERIFY_PARAM_inherit|) after copying |store|'s parameters. This means -// it is impossible to leave some parameters unset at |store|. They must be -// explicitly unset after creating the |X509_STORE_CTX|. +// WARNING: `X509_STORE_CTX_init` applies some default parameters (as in +// `X509_VERIFY_PARAM_inherit`) after copying `store`'s parameters. This means +// it is impossible to leave some parameters unset at `store`. They must be +// explicitly unset after creating the `X509_STORE_CTX`. // // As of writing these late defaults are a depth limit (see -// |X509_VERIFY_PARAM_set_depth|) and the |X509_V_FLAG_TRUSTED_FIRST| flag. This -// warning does not apply if the parameters were set in |store|. +// `X509_VERIFY_PARAM_set_depth`) and the `X509_V_FLAG_TRUSTED_FIRST` flag. This +// warning does not apply if the parameters were set in `store`. // // TODO(crbug.com/boringssl/441): This behavior is very surprising. Can we -// remove this notion of late defaults? The unsettable value at |X509_STORE| is +// remove this notion of late defaults? The unsettable value at `X509_STORE` is // -1, which rejects everything but explicitly-trusted self-signed certificates. -// |X509_V_FLAG_TRUSTED_FIRST| is mostly a workaround for poor path-building. +// `X509_V_FLAG_TRUSTED_FIRST` is mostly a workaround for poor path-building. OPENSSL_EXPORT X509_VERIFY_PARAM *X509_STORE_get0_param(X509_STORE *store); -// X509_STORE_set1_param copies verification parameters from |param| as in -// |X509_VERIFY_PARAM_set1|. It returns one on success and zero on error. +// X509_STORE_set1_param copies verification parameters from `param` as in +// `X509_VERIFY_PARAM_set1`. It returns one on success and zero on error. OPENSSL_EXPORT int X509_STORE_set1_param(X509_STORE *store, const X509_VERIFY_PARAM *param); -// X509_STORE_set_flags enables all values in |flags| in |store|'s verification -// flags. |flags| should be a combination of |X509_V_FLAG_*| constants. +// X509_STORE_set_flags enables all values in `flags` in `store`'s verification +// flags. `flags` should be a combination of `X509_V_FLAG_*` constants. // // WARNING: These flags will be combined with default flags when copied to an -// |X509_STORE_CTX|. This means it is impossible to unset those defaults from -// the |X509_STORE|. See discussion in |X509_STORE_get0_param|. +// `X509_STORE_CTX`. This means it is impossible to unset those defaults from +// the `X509_STORE`. See discussion in `X509_STORE_get0_param`. OPENSSL_EXPORT int X509_STORE_set_flags(X509_STORE *store, unsigned long flags); -// X509_STORE_set_depth configures |store| to, by default, limit certificate -// chains to |depth| intermediate certificates. This count excludes both the +// X509_STORE_set_depth configures `store` to, by default, limit certificate +// chains to `depth` intermediate certificates. This count excludes both the // target certificate and the trust anchor (root certificate). OPENSSL_EXPORT int X509_STORE_set_depth(X509_STORE *store, int depth); -// X509_STORE_set_purpose configures the purpose check for |store|. See -// |X509_VERIFY_PARAM_set_purpose| for details. +// X509_STORE_set_purpose configures the purpose check for `store`. See +// `X509_VERIFY_PARAM_set_purpose` for details. OPENSSL_EXPORT int X509_STORE_set_purpose(X509_STORE *store, int purpose); -// X509_STORE_set_trust configures the trust check for |store|. See -// |X509_VERIFY_PARAM_set_trust| for details. +// X509_STORE_set_trust configures the trust check for `store`. See +// `X509_VERIFY_PARAM_set_trust` for details. OPENSSL_EXPORT int X509_STORE_set_trust(X509_STORE *store, int trust); -// The following constants indicate the type of an |X509_OBJECT|. +// The following constants indicate the type of an `X509_OBJECT`. #define X509_LU_NONE 0 #define X509_LU_X509 1 #define X509_LU_CRL 2 @@ -2890,28 +2890,28 @@ DEFINE_STACK_OF(X509_OBJECT) -// X509_OBJECT_new returns a newly-allocated, empty |X509_OBJECT| or NULL on +// X509_OBJECT_new returns a newly-allocated, empty `X509_OBJECT` or NULL on // error. OPENSSL_EXPORT X509_OBJECT *X509_OBJECT_new(void); -// X509_OBJECT_free releases memory associated with |obj|. +// X509_OBJECT_free releases memory associated with `obj`. OPENSSL_EXPORT void X509_OBJECT_free(X509_OBJECT *obj); -// X509_OBJECT_get_type returns the type of |obj|, which will be one of the -// |X509_LU_*| constants. +// X509_OBJECT_get_type returns the type of `obj`, which will be one of the +// `X509_LU_*` constants. OPENSSL_EXPORT int X509_OBJECT_get_type(const X509_OBJECT *obj); -// X509_OBJECT_get0_X509 returns |obj| as a certificate, or NULL if |obj| is not +// X509_OBJECT_get0_X509 returns `obj` as a certificate, or NULL if `obj` is not // a certificate. OPENSSL_EXPORT X509 *X509_OBJECT_get0_X509(const X509_OBJECT *obj); // X509_STORE_get1_objects returns a newly-allocated stack containing the -// contents of |store|, or NULL on error. The caller must release the result -// with |sk_X509_OBJECT_pop_free| and |X509_OBJECT_free| when done. +// contents of `store`, or NULL on error. The caller must release the result +// with `sk_X509_OBJECT_pop_free` and `X509_OBJECT_free` when done. // // The result will include all certificates and CRLs added via -// |X509_STORE_add_cert| and |X509_STORE_add_crl|, as well as any cached objects -// added by |X509_LOOKUP_add_dir|. The last of these may change over time, as +// `X509_STORE_add_cert` and `X509_STORE_add_crl`, as well as any cached objects +// added by `X509_LOOKUP_add_dir`. The last of these may change over time, as // different objects are loaded from the filesystem. Callers should not depend // on this caching behavior. The objects are returned in no particular order. OPENSSL_EXPORT STACK_OF(X509_OBJECT) *X509_STORE_get1_objects( @@ -2920,41 +2920,41 @@ // Certificate verification. // -// An |X509_STORE_CTX| object represents a single certificate verification +// An `X509_STORE_CTX` object represents a single certificate verification // operation. To verify a certificate chain, callers construct an -// |X509_STORE_CTX|, initialize it with |X509_STORE_CTX_init|, configure extra -// parameters with |X509_STORE_CTX_get0_param|, and call |X509_verify_cert|. +// `X509_STORE_CTX`, initialize it with `X509_STORE_CTX_init`, configure extra +// parameters with `X509_STORE_CTX_get0_param`, and call `X509_verify_cert`. -// X509_STORE_CTX_new returns a newly-allocated, empty |X509_STORE_CTX|, or NULL +// X509_STORE_CTX_new returns a newly-allocated, empty `X509_STORE_CTX`, or NULL // on error. OPENSSL_EXPORT X509_STORE_CTX *X509_STORE_CTX_new(void); -// X509_STORE_CTX_free releases memory associated with |ctx|. +// X509_STORE_CTX_free releases memory associated with `ctx`. OPENSSL_EXPORT void X509_STORE_CTX_free(X509_STORE_CTX *ctx); -// X509_STORE_CTX_init initializes |ctx| to verify |x509|, using trusted -// certificates and parameters in |store|. It returns one on success and zero on -// error. |chain| is a list of untrusted intermediate certificates to use in +// X509_STORE_CTX_init initializes `ctx` to verify `x509`, using trusted +// certificates and parameters in `store`. It returns one on success and zero on +// error. `chain` is a list of untrusted intermediate certificates to use in // verification. // -// |ctx| stores pointers to |store|, |x509|, and |chain|. Each of these objects -// must outlive |ctx| and may not be mutated for the duration of the certificate +// `ctx` stores pointers to `store`, `x509`, and `chain`. Each of these objects +// must outlive `ctx` and may not be mutated for the duration of the certificate // verification. OPENSSL_EXPORT int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, X509 *x509, STACK_OF(X509) *chain); -// X509_verify_cert performs certificate verification with |ctx|, which must -// have been initialized with |X509_STORE_CTX_init|. It returns one on success -// and zero on error. On success, |X509_STORE_CTX_get0_chain| or -// |X509_STORE_CTX_get1_chain| may be used to return the verified certificate -// chain. On error, |X509_STORE_CTX_get_error| may be used to return additional +// X509_verify_cert performs certificate verification with `ctx`, which must +// have been initialized with `X509_STORE_CTX_init`. It returns one on success +// and zero on error. On success, `X509_STORE_CTX_get0_chain` or +// `X509_STORE_CTX_get1_chain` may be used to return the verified certificate +// chain. On error, `X509_STORE_CTX_get_error` may be used to return additional // error information. // // WARNING: Most failure conditions from this function do not use the error -// queue. Use |X509_STORE_CTX_get_error| to determine the cause of the error. +// queue. Use `X509_STORE_CTX_get_error` to determine the cause of the error. OPENSSL_EXPORT int X509_verify_cert(X509_STORE_CTX *ctx); -// X509_STORE_CTX_get0_chain, after a successful |X509_verify_cert| call, +// X509_STORE_CTX_get0_chain, after a successful `X509_verify_cert` call, // returns the verified certificate chain. The chain begins with the leaf and // ends with trust anchor. // @@ -2965,14 +2965,14 @@ OPENSSL_EXPORT STACK_OF(X509) *X509_STORE_CTX_get0_chain( const X509_STORE_CTX *ctx); -// X509_STORE_CTX_get1_chain behaves like |X509_STORE_CTX_get0_chain| but -// returns a newly-allocated |STACK_OF(X509)| containing the completed chain, +// X509_STORE_CTX_get1_chain behaves like `X509_STORE_CTX_get0_chain` but +// returns a newly-allocated `STACK_OF(X509)` containing the completed chain, // with each certificate's reference count incremented. Callers must free the -// result with |sk_X509_pop_free| and |X509_free| when done. +// result with `sk_X509_pop_free` and `X509_free` when done. OPENSSL_EXPORT STACK_OF(X509) *X509_STORE_CTX_get1_chain( const X509_STORE_CTX *ctx); -// The following values are possible outputs of |X509_STORE_CTX_get_error|. +// The following values are possible outputs of `X509_STORE_CTX_get_error`. #define X509_V_OK 0 #define X509_V_ERR_UNSPECIFIED 1 #define X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT 2 @@ -3035,85 +3035,85 @@ #define X509_V_ERR_STORE_LOOKUP 66 #define X509_V_ERR_NAME_CONSTRAINTS_WITHOUT_SANS 67 -// X509_STORE_CTX_get_error, after |X509_verify_cert| returns, returns -// |X509_V_OK| if verification succeeded or an |X509_V_ERR_*| describing why -// verification failed. This will be consistent with |X509_verify_cert|'s return +// X509_STORE_CTX_get_error, after `X509_verify_cert` returns, returns +// `X509_V_OK` if verification succeeded or an `X509_V_ERR_*` describing why +// verification failed. This will be consistent with `X509_verify_cert`'s return // value, unless the caller used the deprecated verification callback (see -// |X509_STORE_CTX_set_verify_cb|) in a way that breaks |ctx|'s invariants. +// `X509_STORE_CTX_set_verify_cb`) in a way that breaks `ctx`'s invariants. // -// If called during the deprecated verification callback when |ok| is zero, it +// If called during the deprecated verification callback when `ok` is zero, it // returns the current error under consideration. OPENSSL_EXPORT int X509_STORE_CTX_get_error(const X509_STORE_CTX *ctx); -// X509_STORE_CTX_set_error sets |ctx|'s error to |err|, which should be -// |X509_V_OK| or an |X509_V_ERR_*| constant. It is not expected to be called in -// typical |X509_STORE_CTX| usage, but may be used in callback APIs where -// applications synthesize |X509_STORE_CTX| error conditions. See also -// |X509_STORE_CTX_set_verify_cb| and |SSL_CTX_set_cert_verify_callback|. +// X509_STORE_CTX_set_error sets `ctx`'s error to `err`, which should be +// `X509_V_OK` or an `X509_V_ERR_*` constant. It is not expected to be called in +// typical `X509_STORE_CTX` usage, but may be used in callback APIs where +// applications synthesize `X509_STORE_CTX` error conditions. See also +// `X509_STORE_CTX_set_verify_cb` and `SSL_CTX_set_cert_verify_callback`. OPENSSL_EXPORT void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx, int err); -// X509_verify_cert_error_string returns |err| as a human-readable string, where -// |err| should be one of the |X509_V_*| values. If |err| is unknown, it returns +// X509_verify_cert_error_string returns `err` as a human-readable string, where +// `err` should be one of the `X509_V_*` values. If `err` is unknown, it returns // a default description. OPENSSL_EXPORT const char *X509_verify_cert_error_string(long err); // X509_STORE_CTX_get_error_depth returns the depth at which the error returned -// by |X509_STORE_CTX_get_error| occurred. This is zero-indexed integer into the +// by `X509_STORE_CTX_get_error` occurred. This is zero-indexed integer into the // certificate chain. Zero indicates the target certificate, one its issuer, and // so on. OPENSSL_EXPORT int X509_STORE_CTX_get_error_depth(const X509_STORE_CTX *ctx); // X509_STORE_CTX_get_current_cert returns the certificate which caused the -// error returned by |X509_STORE_CTX_get_error|. +// error returned by `X509_STORE_CTX_get_error`. OPENSSL_EXPORT X509 *X509_STORE_CTX_get_current_cert(const X509_STORE_CTX *ctx); // X509_STORE_CTX_get0_current_crl returns the CRL which caused the error -// returned by |X509_STORE_CTX_get_error|. +// returned by `X509_STORE_CTX_get_error`. OPENSSL_EXPORT X509_CRL *X509_STORE_CTX_get0_current_crl( const X509_STORE_CTX *ctx); -// X509_STORE_CTX_get0_store returns the |X509_STORE| that |ctx| uses. +// X509_STORE_CTX_get0_store returns the `X509_STORE` that `ctx` uses. OPENSSL_EXPORT X509_STORE *X509_STORE_CTX_get0_store(const X509_STORE_CTX *ctx); -// X509_STORE_CTX_get0_cert returns the leaf certificate that |ctx| is +// X509_STORE_CTX_get0_cert returns the leaf certificate that `ctx` is // verifying. OPENSSL_EXPORT X509 *X509_STORE_CTX_get0_cert(const X509_STORE_CTX *ctx); // X509_STORE_CTX_get0_untrusted returns the stack of untrusted intermediates -// used by |ctx| for certificate verification. +// used by `ctx` for certificate verification. OPENSSL_EXPORT STACK_OF(X509) *X509_STORE_CTX_get0_untrusted( const X509_STORE_CTX *ctx); -// X509_STORE_CTX_set0_trusted_stack configures |ctx| to trust the certificates -// in |sk|. |sk| must remain valid for the duration of |ctx|. Calling this -// function causes |ctx| to ignore any certificates configured in the -// |X509_STORE|. Certificates in |sk| are still subject to the check described -// in |X509_VERIFY_PARAM_set_trust|. +// X509_STORE_CTX_set0_trusted_stack configures `ctx` to trust the certificates +// in `sk`. `sk` must remain valid for the duration of `ctx`. Calling this +// function causes `ctx` to ignore any certificates configured in the +// `X509_STORE`. Certificates in `sk` are still subject to the check described +// in `X509_VERIFY_PARAM_set_trust`. // -// WARNING: This function differs from most |set0| functions in that it does not +// WARNING: This function differs from most `set0` functions in that it does not // take ownership of its input. The caller is required to ensure the lifetimes // are consistent. OPENSSL_EXPORT void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); -// X509_STORE_CTX_set0_crls configures |ctx| to consider the CRLs in |sk| as -// candidates for CRL lookup. |sk| must remain valid for the duration of |ctx|. -// These CRLs are considered in addition to CRLs found in |X509_STORE|. +// X509_STORE_CTX_set0_crls configures `ctx` to consider the CRLs in `sk` as +// candidates for CRL lookup. `sk` must remain valid for the duration of `ctx`. +// These CRLs are considered in addition to CRLs found in `X509_STORE`. // -// WARNING: This function differs from most |set0| functions in that it does not +// WARNING: This function differs from most `set0` functions in that it does not // take ownership of its input. The caller is required to ensure the lifetimes // are consistent. OPENSSL_EXPORT void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); -// X509_STORE_CTX_set_default looks up the set of parameters named |name| and -// applies those default verification parameters for |ctx|. As in -// |X509_VERIFY_PARAM_inherit|, only unset parameters are changed. This function +// X509_STORE_CTX_set_default looks up the set of parameters named `name` and +// applies those default verification parameters for `ctx`. As in +// `X509_VERIFY_PARAM_inherit`, only unset parameters are changed. This function // returns one on success and zero on error. // -// The supported values of |name| are: +// The supported values of `name` are: // - "default" is an internal value which configures some late defaults. See the -// discussion in |X509_STORE_get0_param|. +// discussion in `X509_STORE_get0_param`. // - "pkcs7" configures default trust and purpose checks for PKCS#7 signatures. // - "smime_sign" configures trust and purpose checks for S/MIME signatures. // - "ssl_client" configures trust and purpose checks for TLS clients. @@ -3123,124 +3123,124 @@ OPENSSL_EXPORT int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); -// X509_STORE_CTX_get0_param returns |ctx|'s verification parameters. This +// X509_STORE_CTX_get0_param returns `ctx`'s verification parameters. This // object is mutable and may be modified by the caller. OPENSSL_EXPORT X509_VERIFY_PARAM *X509_STORE_CTX_get0_param( X509_STORE_CTX *ctx); -// X509_STORE_CTX_set0_param returns |ctx|'s verification parameters to |param| -// and takes ownership of |param|. After this function returns, the caller -// should not free |param|. +// X509_STORE_CTX_set0_param returns `ctx`'s verification parameters to `param` +// and takes ownership of `param`. After this function returns, the caller +// should not free `param`. // // WARNING: This function discards any values which were previously applied in -// |ctx|, including the "default" parameters applied late in -// |X509_STORE_CTX_init|. These late defaults are not applied to parameters -// created standalone by |X509_VERIFY_PARAM_new|. +// `ctx`, including the "default" parameters applied late in +// `X509_STORE_CTX_init`. These late defaults are not applied to parameters +// created standalone by `X509_VERIFY_PARAM_new`. // // TODO(crbug.com/boringssl/441): This behavior is very surprising. Should we -// re-apply the late defaults in |param|, or somehow avoid this notion of late +// re-apply the late defaults in `param`, or somehow avoid this notion of late // defaults altogether? OPENSSL_EXPORT void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); -// X509_STORE_CTX_set_flags enables all values in |flags| in |ctx|'s -// verification flags. |flags| should be a combination of |X509_V_FLAG_*| +// X509_STORE_CTX_set_flags enables all values in `flags` in `ctx`'s +// verification flags. `flags` should be a combination of `X509_V_FLAG_*` // constants. OPENSSL_EXPORT void X509_STORE_CTX_set_flags(X509_STORE_CTX *ctx, unsigned long flags); -// X509_STORE_CTX_set_time configures certificate verification to use |t| -// instead of the current time. |flags| is ignored and should be zero. +// X509_STORE_CTX_set_time configures certificate verification to use `t` +// instead of the current time. `flags` is ignored and should be zero. OPENSSL_EXPORT void X509_STORE_CTX_set_time(X509_STORE_CTX *ctx, unsigned long flags, time_t t); -// X509_STORE_CTX_set_time_posix configures certificate verification to use |t| -// instead of the current time. |t| is interpreted as a POSIX timestamp in -// seconds. |flags| is ignored and should be zero. +// X509_STORE_CTX_set_time_posix configures certificate verification to use `t` +// instead of the current time. `t` is interpreted as a POSIX timestamp in +// seconds. `flags` is ignored and should be zero. OPENSSL_EXPORT void X509_STORE_CTX_set_time_posix(X509_STORE_CTX *ctx, unsigned long flags, int64_t t); -// X509_STORE_CTX_set_depth configures |ctx| to, by default, limit certificate -// chains to |depth| intermediate certificates. This count excludes both the +// X509_STORE_CTX_set_depth configures `ctx` to, by default, limit certificate +// chains to `depth` intermediate certificates. This count excludes both the // target certificate and the trust anchor (root certificate). OPENSSL_EXPORT void X509_STORE_CTX_set_depth(X509_STORE_CTX *ctx, int depth); -// X509_STORE_CTX_set_purpose simultaneously configures |ctx|'s purpose and -// trust checks, if unset. It returns one on success and zero if |purpose| is -// not a valid purpose value. |purpose| should be an |X509_PURPOSE_*| constant. -// If so, it configures |ctx| with a purpose check of |purpose| and a trust -// check of |purpose|'s corresponding trust value. If either the purpose or -// trust check had already been specified for |ctx|, that corresponding +// X509_STORE_CTX_set_purpose simultaneously configures `ctx`'s purpose and +// trust checks, if unset. It returns one on success and zero if `purpose` is +// not a valid purpose value. `purpose` should be an `X509_PURPOSE_*` constant. +// If so, it configures `ctx` with a purpose check of `purpose` and a trust +// check of `purpose`'s corresponding trust value. If either the purpose or +// trust check had already been specified for `ctx`, that corresponding // modification is silently dropped. // -// See |X509_VERIFY_PARAM_set_purpose| and |X509_VERIFY_PARAM_set_trust| for +// See `X509_VERIFY_PARAM_set_purpose` and `X509_VERIFY_PARAM_set_trust` for // details on the purpose and trust checks, respectively. // -// If |purpose| is |X509_PURPOSE_ANY|, this function returns an error because it -// has no corresponding |X509_TRUST_*| value. It is not possible to set -// |X509_PURPOSE_ANY| with this function, only |X509_VERIFY_PARAM_set_purpose|. +// If `purpose` is `X509_PURPOSE_ANY`, this function returns an error because it +// has no corresponding `X509_TRUST_*` value. It is not possible to set +// `X509_PURPOSE_ANY` with this function, only `X509_VERIFY_PARAM_set_purpose`. // // WARNING: Unlike similarly named functions in this header, this function -// silently does not behave the same as |X509_VERIFY_PARAM_set_purpose|. Callers -// may use |X509_VERIFY_PARAM_set_purpose| with |X509_STORE_CTX_get0_param| to +// silently does not behave the same as `X509_VERIFY_PARAM_set_purpose`. Callers +// may use `X509_VERIFY_PARAM_set_purpose` with `X509_STORE_CTX_get0_param` to // avoid this difference. OPENSSL_EXPORT int X509_STORE_CTX_set_purpose(X509_STORE_CTX *ctx, int purpose); -// X509_STORE_CTX_set_trust configures |ctx|'s trust check, if unset. It returns -// one on success and zero if |trust| is not a valid trust value. |trust| should -// be an |X509_TRUST_*| constant. If so, it configures |ctx| with a trust check -// of |trust|. If the trust check had already been specified for |ctx|, it +// X509_STORE_CTX_set_trust configures `ctx`'s trust check, if unset. It returns +// one on success and zero if `trust` is not a valid trust value. `trust` should +// be an `X509_TRUST_*` constant. If so, it configures `ctx` with a trust check +// of `trust`. If the trust check had already been specified for `ctx`, it // silently does nothing. // -// See |X509_VERIFY_PARAM_set_trust| for details on the purpose and trust check. +// See `X509_VERIFY_PARAM_set_trust` for details on the purpose and trust check. // // WARNING: Unlike similarly named functions in this header, this function -// does not behave the same as |X509_VERIFY_PARAM_set_trust|. Callers may use -// |X509_VERIFY_PARAM_set_trust| with |X509_STORE_CTX_get0_param| to avoid this +// does not behave the same as `X509_VERIFY_PARAM_set_trust`. Callers may use +// `X509_VERIFY_PARAM_set_trust` with `X509_STORE_CTX_get0_param` to avoid this // difference. OPENSSL_EXPORT int X509_STORE_CTX_set_trust(X509_STORE_CTX *ctx, int trust); // Verification parameters. // -// An |X509_VERIFY_PARAM| contains a set of parameters for certificate +// An `X509_VERIFY_PARAM` contains a set of parameters for certificate // verification. -// X509_VERIFY_PARAM_new returns a newly-allocated |X509_VERIFY_PARAM|, or NULL +// X509_VERIFY_PARAM_new returns a newly-allocated `X509_VERIFY_PARAM`, or NULL // on error. OPENSSL_EXPORT X509_VERIFY_PARAM *X509_VERIFY_PARAM_new(void); -// X509_VERIFY_PARAM_free releases memory associated with |param|. +// X509_VERIFY_PARAM_free releases memory associated with `param`. OPENSSL_EXPORT void X509_VERIFY_PARAM_free(X509_VERIFY_PARAM *param); -// X509_VERIFY_PARAM_inherit applies |from| as the default values for |to|. That -// is, for each parameter that is unset in |to|, it copies the value in |from|. +// X509_VERIFY_PARAM_inherit applies `from` as the default values for `to`. That +// is, for each parameter that is unset in `to`, it copies the value in `from`. // This function returns one on success and zero on error. OPENSSL_EXPORT int X509_VERIFY_PARAM_inherit(X509_VERIFY_PARAM *to, const X509_VERIFY_PARAM *from); -// X509_VERIFY_PARAM_set1 copies parameters from |from| to |to|. If a parameter -// is unset in |from|, the existing value in |to| is preserved. This function +// X509_VERIFY_PARAM_set1 copies parameters from `from` to `to`. If a parameter +// is unset in `from`, the existing value in `to` is preserved. This function // returns one on success and zero on error. OPENSSL_EXPORT int X509_VERIFY_PARAM_set1(X509_VERIFY_PARAM *to, const X509_VERIFY_PARAM *from); -// X509_V_FLAG_* are flags for |X509_VERIFY_PARAM_set_flags| and -// |X509_VERIFY_PARAM_clear_flags|. +// X509_V_FLAG_* are flags for `X509_VERIFY_PARAM_set_flags` and +// `X509_VERIFY_PARAM_clear_flags`. // X509_V_FLAG_CB_ISSUER_CHECK causes the deprecated verify callback (see -// |X509_STORE_CTX_set_verify_cb|) to be called for errors while matching +// `X509_STORE_CTX_set_verify_cb`) to be called for errors while matching // subject and issuer certificates. #define X509_V_FLAG_CB_ISSUER_CHECK 0x1 // X509_V_FLAG_USE_CHECK_TIME is an internal flag used to track whether -// |X509_STORE_CTX_set_time| has been used. If cleared, the system time is +// `X509_STORE_CTX_set_time` has been used. If cleared, the system time is // restored. #define X509_V_FLAG_USE_CHECK_TIME 0x2 // X509_V_FLAG_CRL_CHECK enables CRL lookup and checking for the leaf. #define X509_V_FLAG_CRL_CHECK 0x4 // X509_V_FLAG_CRL_CHECK_ALL enables CRL lookup and checking for the entire -// certificate chain. |X509_V_FLAG_CRL_CHECK| must be set for this flag to take +// certificate chain. `X509_V_FLAG_CRL_CHECK` must be set for this flag to take // effect. #define X509_V_FLAG_CRL_CHECK_ALL 0x8 // X509_V_FLAG_IGNORE_CRITICAL ignores unhandled critical extensions. Do not use @@ -3281,7 +3281,7 @@ // enabled by default. #define X509_V_FLAG_TRUSTED_FIRST 0x8000 // X509_V_FLAG_PARTIAL_CHAIN treats all trusted certificates as trust anchors, -// independent of the |X509_VERIFY_PARAM_set_trust| setting. +// independent of the `X509_VERIFY_PARAM_set_trust` setting. #define X509_V_FLAG_PARTIAL_CHAIN 0x80000 // X509_V_FLAG_NO_ALT_CHAINS disables building alternative chains if the initial // one was rejected. @@ -3290,76 +3290,76 @@ // verification. #define X509_V_FLAG_NO_CHECK_TIME 0x200000 -// X509_VERIFY_PARAM_set_flags enables all values in |flags| in |param|'s -// verification flags and returns one. |flags| should be a combination of -// |X509_V_FLAG_*| constants. +// X509_VERIFY_PARAM_set_flags enables all values in `flags` in `param`'s +// verification flags and returns one. `flags` should be a combination of +// `X509_V_FLAG_*` constants. OPENSSL_EXPORT int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, unsigned long flags); -// X509_VERIFY_PARAM_clear_flags disables all values in |flags| in |param|'s -// verification flags and returns one. |flags| should be a combination of -// |X509_V_FLAG_*| constants. +// X509_VERIFY_PARAM_clear_flags disables all values in `flags` in `param`'s +// verification flags and returns one. `flags` should be a combination of +// `X509_V_FLAG_*` constants. OPENSSL_EXPORT int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, unsigned long flags); -// X509_VERIFY_PARAM_get_flags returns |param|'s verification flags. +// X509_VERIFY_PARAM_get_flags returns `param`'s verification flags. OPENSSL_EXPORT unsigned long X509_VERIFY_PARAM_get_flags( const X509_VERIFY_PARAM *param); -// X509_VERIFY_PARAM_set_depth configures |param| to limit certificate chains to -// |depth| intermediate certificates. This count excludes both the target +// X509_VERIFY_PARAM_set_depth configures `param` to limit certificate chains to +// `depth` intermediate certificates. This count excludes both the target // certificate and the trust anchor (root certificate). OPENSSL_EXPORT void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); -// X509_VERIFY_PARAM_get_depth returns the maximum depth configured in |param|. -// See |X509_VERIFY_PARAM_set_depth|. +// X509_VERIFY_PARAM_get_depth returns the maximum depth configured in `param`. +// See `X509_VERIFY_PARAM_set_depth`. OPENSSL_EXPORT int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); -// X509_VERIFY_PARAM_set_time configures certificate verification to use |t| +// X509_VERIFY_PARAM_set_time configures certificate verification to use `t` // instead of the current time. OPENSSL_EXPORT void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); // X509_VERIFY_PARAM_set_time_posix configures certificate verification to use -// |t| instead of the current time. |t| is interpreted as a POSIX timestamp in +// `t` instead of the current time. `t` is interpreted as a POSIX timestamp in // seconds. OPENSSL_EXPORT void X509_VERIFY_PARAM_set_time_posix(X509_VERIFY_PARAM *param, int64_t t); -// X509_VERIFY_PARAM_add0_policy adds |policy| to the user-initial-policy-set +// X509_VERIFY_PARAM_add0_policy adds `policy` to the user-initial-policy-set // (see Section 6.1.1 of RFC 5280). On success, it takes ownership of -// |policy| and returns one. Otherwise, it returns zero and the caller retains -// owneship of |policy|. +// `policy` and returns one. Otherwise, it returns zero and the caller retains +// owneship of `policy`. OPENSSL_EXPORT int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, ASN1_OBJECT *policy); // X509_VERIFY_PARAM_set1_policies sets the user-initial-policy-set (see -// Section 6.1.1 of RFC 5280) to a copy of |policies|. It returns one on success +// Section 6.1.1 of RFC 5280) to a copy of `policies`. It returns one on success // and zero on error. OPENSSL_EXPORT int X509_VERIFY_PARAM_set1_policies( X509_VERIFY_PARAM *param, const STACK_OF(ASN1_OBJECT) *policies); -// X509_VERIFY_PARAM_set1_host configures |param| to check for the DNS name -// specified by |name|. It returns one on success and zero on error. +// X509_VERIFY_PARAM_set1_host configures `param` to check for the DNS name +// specified by `name`. It returns one on success and zero on error. // // By default, both subject alternative names and the subject's common name // attribute are checked. The latter has long been deprecated, so callers should -// call |X509_VERIFY_PARAM_set_hostflags| with -// |X509_CHECK_FLAG_NEVER_CHECK_SUBJECT| to use the standard behavior. +// call `X509_VERIFY_PARAM_set_hostflags` with +// `X509_CHECK_FLAG_NEVER_CHECK_SUBJECT` to use the standard behavior. // https://crbug.com/boringssl/464 tracks fixing the default. OPENSSL_EXPORT int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, const char *name, size_t name_len); -// X509_VERIFY_PARAM_add1_host adds |name| to the list of names checked by -// |param|. If any configured DNS name matches the certificate, verification +// X509_VERIFY_PARAM_add1_host adds `name` to the list of names checked by +// `param`. If any configured DNS name matches the certificate, verification // succeeds. It returns one on success and zero on error. // // By default, both subject alternative names and the subject's common name // attribute are checked. The latter has long been deprecated, so callers should -// call |X509_VERIFY_PARAM_set_hostflags| with -// |X509_CHECK_FLAG_NEVER_CHECK_SUBJECT| to use the standard behavior. +// call `X509_VERIFY_PARAM_set_hostflags` with +// `X509_CHECK_FLAG_NEVER_CHECK_SUBJECT` to use the standard behavior. // https://crbug.com/boringssl/464 tracks fixing the default. OPENSSL_EXPORT int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param, const char *name, @@ -3372,30 +3372,30 @@ // enabled when subjectAltNames is missing. #define X509_CHECK_FLAG_NEVER_CHECK_SUBJECT 0x20 -// X509_VERIFY_PARAM_set_hostflags sets the name-checking flags on |param| to -// |flags|. |flags| should be a combination of |X509_CHECK_FLAG_*| constants. +// X509_VERIFY_PARAM_set_hostflags sets the name-checking flags on `param` to +// `flags`. `flags` should be a combination of `X509_CHECK_FLAG_*` constants. OPENSSL_EXPORT void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param, unsigned int flags); -// X509_VERIFY_PARAM_set1_email configures |param| to check for the email -// address specified by |email|. It returns one on success and zero on error. +// X509_VERIFY_PARAM_set1_email configures `param` to check for the email +// address specified by `email`. It returns one on success and zero on error. // // By default, both subject alternative names and the subject's email address -// attribute are checked. The |X509_CHECK_FLAG_NEVER_CHECK_SUBJECT| flag may be +// attribute are checked. The `X509_CHECK_FLAG_NEVER_CHECK_SUBJECT` flag may be // used to change this behavior. OPENSSL_EXPORT int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param, const char *email, size_t email_len); -// X509_VERIFY_PARAM_set1_ip configures |param| to check for the IP address -// specified by |ip|. It returns one on success and zero on error. The IP -// address is specified in its binary representation. |ip_len| must be 4 for an +// X509_VERIFY_PARAM_set1_ip configures `param` to check for the IP address +// specified by `ip`. It returns one on success and zero on error. The IP +// address is specified in its binary representation. `ip_len` must be 4 for an // IPv4 address and 16 for an IPv6 address. OPENSSL_EXPORT int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param, const uint8_t *ip, size_t ip_len); -// X509_VERIFY_PARAM_set1_ip_asc decodes |ipasc| as the ASCII representation of -// an IPv4 or IPv6 address, and configures |param| to check for it. It returns +// X509_VERIFY_PARAM_set1_ip_asc decodes `ipasc` as the ASCII representation of +// an IPv4 or IPv6 address, and configures `param` to check for it. It returns // one on success and zero on error. OPENSSL_EXPORT int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc); @@ -3411,7 +3411,7 @@ // usage specific to the negotiated TLS parameters. #define X509_PURPOSE_SSL_SERVER 2 // X509_PURPOSE_NS_SSL_SERVER is a legacy mode. It behaves like -// |X509_PURPOSE_SSL_SERVER|, but only accepts the keyEncipherment key usage, +// `X509_PURPOSE_SSL_SERVER`, but only accepts the keyEncipherment key usage, // used by SSL 2.0 and RSA key exchange. Do not use this. #define X509_PURPOSE_NS_SSL_SERVER 3 // X509_PURPOSE_SMIME_SIGN validates S/MIME signing certificates. It checks for @@ -3439,9 +3439,9 @@ // asserted. #define X509_PURPOSE_TIMESTAMP_SIGN 9 -// X509_VERIFY_PARAM_set_purpose configures |param| to validate certificates for -// a specified purpose. It returns one on success and zero if |purpose| is not a -// valid purpose type. |purpose| should be one of the |X509_PURPOSE_*| values. +// X509_VERIFY_PARAM_set_purpose configures `param` to validate certificates for +// a specified purpose. It returns one on success and zero if `purpose` is not a +// valid purpose type. `purpose` should be one of the `X509_PURPOSE_*` values. // // This option controls checking the extended key usage (EKU) and key usage // extensions. These extensions specify how a certificate's public key may be @@ -3455,13 +3455,13 @@ // not accept anyExtendedKeyUsage. // // Many purpose values have a corresponding trust value, which is not configured -// by this function. See |X509_VERIFY_PARAM_set_trust| for details. Callers +// by this function. See `X509_VERIFY_PARAM_set_trust` for details. Callers // that wish to configure both should either call both functions, or use -// |X509_STORE_CTX_set_purpose|. +// `X509_STORE_CTX_set_purpose`. // // It is currently not possible to configure custom EKU OIDs or key usage bits. // Contact the BoringSSL maintainers if your application needs to do so. OpenSSL -// had an |X509_PURPOSE_add| API, but it was not thread-safe and relied on +// had an `X509_PURPOSE_add` API, but it was not thread-safe and relied on // global mutable state, so we removed it. // // TODO(davidben): This function additionally configures checking the legacy @@ -3472,52 +3472,52 @@ // X509_TRUST_COMPAT evaluates trust using only the self-signed fallback. Trust // and distrust OIDs are ignored. #define X509_TRUST_COMPAT 1 -// X509_TRUST_SSL_CLIENT evaluates trust with the |NID_client_auth| OID, for +// X509_TRUST_SSL_CLIENT evaluates trust with the `NID_client_auth` OID, for // validating TLS client certificates. #define X509_TRUST_SSL_CLIENT 2 -// X509_TRUST_SSL_SERVER evaluates trust with the |NID_server_auth| OID, for +// X509_TRUST_SSL_SERVER evaluates trust with the `NID_server_auth` OID, for // validating TLS server certificates. #define X509_TRUST_SSL_SERVER 3 -// X509_TRUST_EMAIL evaluates trust with the |NID_email_protect| OID, for +// X509_TRUST_EMAIL evaluates trust with the `NID_email_protect` OID, for // validating S/MIME email certificates. #define X509_TRUST_EMAIL 4 -// X509_TRUST_OBJECT_SIGN evaluates trust with the |NID_code_sign| OID, for +// X509_TRUST_OBJECT_SIGN evaluates trust with the `NID_code_sign` OID, for // validating code signing certificates. #define X509_TRUST_OBJECT_SIGN 5 -// X509_TRUST_TSA evaluates trust with the |NID_time_stamp| OID, for validating +// X509_TRUST_TSA evaluates trust with the `NID_time_stamp` OID, for validating // Time Stamping Authority (RFC 3161) certificates. #define X509_TRUST_TSA 8 -// X509_VERIFY_PARAM_set_trust configures which certificates from |X509_STORE| -// are trust anchors. It returns one on success and zero if |trust| is not a -// valid trust value. |trust| should be one of the |X509_TRUST_*| constants. +// X509_VERIFY_PARAM_set_trust configures which certificates from `X509_STORE` +// are trust anchors. It returns one on success and zero if `trust` is not a +// valid trust value. `trust` should be one of the `X509_TRUST_*` constants. // This function allows applications to vary trust anchors when the same set of // trusted certificates is used in multiple contexts. // // Two properties determine whether a certificate is a trust anchor: // // - Whether it is trusted or distrusted for some OID, via auxiliary information -// configured by |X509_add1_trust_object| or |X509_add1_reject_object|. +// configured by `X509_add1_trust_object` or `X509_add1_reject_object`. // -// - Whether it is "self-signed". That is, whether |X509_get_extension_flags| -// includes |EXFLAG_SS|. The signature itself is not checked. +// - Whether it is "self-signed". That is, whether `X509_get_extension_flags` +// includes `EXFLAG_SS`. The signature itself is not checked. // -// When this function is called, |trust| determines the OID to check in the +// When this function is called, `trust` determines the OID to check in the // first case. If the certificate is not explicitly trusted or distrusted for // any OID, it is trusted if self-signed instead. // -// If unset, the default behavior is to check for the |NID_anyExtendedKeyUsage| +// If unset, the default behavior is to check for the `NID_anyExtendedKeyUsage` // OID. If the certificate is not explicitly trusted or distrusted for this OID, // it is trusted if self-signed instead. Note this slightly differs from the // above. // -// If the |X509_V_FLAG_PARTIAL_CHAIN| is set, every certificate from -// |X509_STORE| is a trust anchor, unless it was explicitly distrusted for the +// If the `X509_V_FLAG_PARTIAL_CHAIN` is set, every certificate from +// `X509_STORE` is a trust anchor, unless it was explicitly distrusted for the // OID. // // It is currently not possible to configure custom trust OIDs. Contact the // BoringSSL maintainers if your application needs to do so. OpenSSL had an -// |X509_TRUST_add| API, but it was not thread-safe and relied on global mutable +// `X509_TRUST_add` API, but it was not thread-safe and relied on global mutable // state, so we removed it. OPENSSL_EXPORT int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); @@ -3525,160 +3525,160 @@ // Filesystem-based certificate stores. // -// An |X509_STORE| may be configured to get its contents from the filesystem. -// This is done by adding |X509_LOOKUP| structures to the |X509_STORE| with -// |X509_STORE_add_lookup| and then configuring the |X509_LOOKUP| with paths. +// An `X509_STORE` may be configured to get its contents from the filesystem. +// This is done by adding `X509_LOOKUP` structures to the `X509_STORE` with +// `X509_STORE_add_lookup` and then configuring the `X509_LOOKUP` with paths. // -// Most cases can use |X509_STORE_load_locations|, which configures the same +// Most cases can use `X509_STORE_load_locations`, which configures the same // thing but is simpler to use. -// X509_STORE_load_locations configures |store| to load data from filepaths -// |file| and |dir|. It returns one on success and zero on error. Either of -// |file| or |dir| may be NULL, but at least one must be non-NULL. +// X509_STORE_load_locations configures `store` to load data from filepaths +// `file` and `dir`. It returns one on success and zero on error. Either of +// `file` or `dir` may be NULL, but at least one must be non-NULL. // -// If |file| is non-NULL, it loads CRLs and trusted certificates in PEM format -// from the file at |file|, and them to |store|, as in |X509_load_cert_crl_file| -// with |X509_FILETYPE_PEM|. +// If `file` is non-NULL, it loads CRLs and trusted certificates in PEM format +// from the file at `file`, and them to `store`, as in `X509_load_cert_crl_file` +// with `X509_FILETYPE_PEM`. // -// If |dir| is non-NULL, it configures |store| to load CRLs and trusted -// certificates from the directory at |dir| in PEM format, as in -// |X509_LOOKUP_add_dir| with |X509_FILETYPE_PEM|. +// If `dir` is non-NULL, it configures `store` to load CRLs and trusted +// certificates from the directory at `dir` in PEM format, as in +// `X509_LOOKUP_add_dir` with `X509_FILETYPE_PEM`. OPENSSL_EXPORT int X509_STORE_load_locations(X509_STORE *store, const char *file, const char *dir); -// X509_STORE_add_lookup returns an |X509_LOOKUP| associated with |store| with -// type |method|, or NULL on error. The result is owned by |store|, so callers -// are not expected to free it. This may be used with |X509_LOOKUP_add_dir| or -// |X509_LOOKUP_load_file|, depending on |method|, to configure |store|. +// X509_STORE_add_lookup returns an `X509_LOOKUP` associated with `store` with +// type `method`, or NULL on error. The result is owned by `store`, so callers +// are not expected to free it. This may be used with `X509_LOOKUP_add_dir` or +// `X509_LOOKUP_load_file`, depending on `method`, to configure `store`. // -// A single |X509_LOOKUP| may be configured with multiple paths, and an -// |X509_STORE| only contains one |X509_LOOKUP| of each type, so there is no +// A single `X509_LOOKUP` may be configured with multiple paths, and an +// `X509_STORE` only contains one `X509_LOOKUP` of each type, so there is no // need to call this function multiple times for a single type. Calling it -// multiple times will return the previous |X509_LOOKUP| of that type. +// multiple times will return the previous `X509_LOOKUP` of that type. OPENSSL_EXPORT X509_LOOKUP *X509_STORE_add_lookup( X509_STORE *store, const X509_LOOKUP_METHOD *method); -// X509_LOOKUP_hash_dir creates |X509_LOOKUP|s that may be used with -// |X509_LOOKUP_add_dir|. +// X509_LOOKUP_hash_dir creates `X509_LOOKUP`s that may be used with +// `X509_LOOKUP_add_dir`. OPENSSL_EXPORT const X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void); -// X509_LOOKUP_file creates |X509_LOOKUP|s that may be used with -// |X509_LOOKUP_load_file|. +// X509_LOOKUP_file creates `X509_LOOKUP`s that may be used with +// `X509_LOOKUP_load_file`. // -// Although this is modeled as an |X509_LOOKUP|, this function is redundant. It +// Although this is modeled as an `X509_LOOKUP`, this function is redundant. It // has the same effect as loading a certificate or CRL from the filesystem, in -// the caller's desired format, and then adding it with |X509_STORE_add_cert| -// and |X509_STORE_add_crl|. +// the caller's desired format, and then adding it with `X509_STORE_add_cert` +// and `X509_STORE_add_crl`. OPENSSL_EXPORT const X509_LOOKUP_METHOD *X509_LOOKUP_file(void); // The following constants are used to specify the format of files in an -// |X509_LOOKUP|. +// `X509_LOOKUP`. #define X509_FILETYPE_PEM 1 #define X509_FILETYPE_ASN1 2 #define X509_FILETYPE_DEFAULT 3 -// X509_LOOKUP_load_file calls |X509_load_cert_crl_file|. |lookup| must have -// been constructed with |X509_LOOKUP_file|. +// X509_LOOKUP_load_file calls `X509_load_cert_crl_file`. `lookup` must have +// been constructed with `X509_LOOKUP_file`. // -// If |type| is |X509_FILETYPE_DEFAULT|, it ignores |file| and instead uses some -// default system path with |X509_FILETYPE_PEM|. See also -// |X509_STORE_set_default_paths|. +// If `type` is `X509_FILETYPE_DEFAULT`, it ignores `file` and instead uses some +// default system path with `X509_FILETYPE_PEM`. See also +// `X509_STORE_set_default_paths`. OPENSSL_EXPORT int X509_LOOKUP_load_file(X509_LOOKUP *lookup, const char *file, int type); -// X509_LOOKUP_add_dir configures |lookup| to load CRLs and trusted certificates -// from the directories in |path|. It returns one on success and zero on error. -// |lookup| must have been constructed with |X509_LOOKUP_hash_dir|. +// X509_LOOKUP_add_dir configures `lookup` to load CRLs and trusted certificates +// from the directories in `path`. It returns one on success and zero on error. +// `lookup` must have been constructed with `X509_LOOKUP_hash_dir`. // -// WARNING: |path| is interpreted as a colon-separated (semicolon-separated on +// WARNING: `path` is interpreted as a colon-separated (semicolon-separated on // Windows) list of paths. It is not possible to configure a path containing the // separator character. https://crbug.com/boringssl/691 tracks removing this // behavior. // -// |type| should be one of the |X509_FILETYPE_*| constants and determines the -// format of the files. If |type| is |X509_FILETYPE_DEFAULT|, |path| is ignored -// and some default system path is used with |X509_FILETYPE_PEM|. See also -// |X509_STORE_set_default_paths|. +// `type` should be one of the `X509_FILETYPE_*` constants and determines the +// format of the files. If `type` is `X509_FILETYPE_DEFAULT`, `path` is ignored +// and some default system path is used with `X509_FILETYPE_PEM`. See also +// `X509_STORE_set_default_paths`. // // Trusted certificates should be named HASH.N and CRLs should be -// named HASH.rN. HASH is |X509_NAME_hash| of the certificate subject and CRL +// named HASH.rN. HASH is `X509_NAME_hash` of the certificate subject and CRL // issuer, respectively, in hexadecimal. N is in decimal and counts hash // collisions consecutively, starting from zero. For example, "002c0b4f.0" and // "002c0b4f.r0". // -// WARNING: Objects from |path| are loaded on demand, but cached in memory on -// the |X509_STORE|. If a CA is removed from the directory, existing -// |X509_STORE|s will continue to trust it. Cache entries are not evicted for -// the lifetime of the |X509_STORE|. +// WARNING: Objects from `path` are loaded on demand, but cached in memory on +// the `X509_STORE`. If a CA is removed from the directory, existing +// `X509_STORE`s will continue to trust it. Cache entries are not evicted for +// the lifetime of the `X509_STORE`. // // WARNING: This mechanism is also not well-suited for CRL updates. -// |X509_STORE|s rely on this cache and never load the same CRL file twice. CRL +// `X509_STORE`s rely on this cache and never load the same CRL file twice. CRL // updates must use a new file, with an incremented suffix, to be reflected in -// existing |X509_STORE|s. However, this means each CRL update will use +// existing `X509_STORE`s. However, this means each CRL update will use // additional storage and memory. Instead, configure inputs that vary per -// verification, such as CRLs, on each |X509_STORE_CTX| separately, using -// functions like |X509_STORE_CTX_set0_crl|. +// verification, such as CRLs, on each `X509_STORE_CTX` separately, using +// functions like `X509_STORE_CTX_set0_crl`. OPENSSL_EXPORT int X509_LOOKUP_add_dir(X509_LOOKUP *lookup, const char *path, int type); -// X509_L_* are commands for |X509_LOOKUP_ctrl|. +// X509_L_* are commands for `X509_LOOKUP_ctrl`. #define X509_L_FILE_LOAD 1 #define X509_L_ADD_DIR 2 -// X509_LOOKUP_ctrl implements commands on |lookup|. |cmd| specifies the +// X509_LOOKUP_ctrl implements commands on `lookup`. `cmd` specifies the // command. The other arguments specify the operation in a command-specific way. -// Use |X509_LOOKUP_load_file| or |X509_LOOKUP_add_dir| instead. +// Use `X509_LOOKUP_load_file` or `X509_LOOKUP_add_dir` instead. OPENSSL_EXPORT int X509_LOOKUP_ctrl(X509_LOOKUP *lookup, int cmd, const char *argc, long argl, char **ret); -// X509_load_cert_file loads trusted certificates from |file| and adds them to -// |lookup|'s |X509_STORE|. It returns one on success and zero on error. +// X509_load_cert_file loads trusted certificates from `file` and adds them to +// `lookup`'s `X509_STORE`. It returns one on success and zero on error. // -// If |type| is |X509_FILETYPE_ASN1|, it loads a single DER-encoded certificate. -// If |type| is |X509_FILETYPE_PEM|, it loads a sequence of PEM-encoded -// certificates. |type| may not be |X509_FILETYPE_DEFAULT|. +// If `type` is `X509_FILETYPE_ASN1`, it loads a single DER-encoded certificate. +// If `type` is `X509_FILETYPE_PEM`, it loads a sequence of PEM-encoded +// certificates. `type` may not be `X509_FILETYPE_DEFAULT`. OPENSSL_EXPORT int X509_load_cert_file(X509_LOOKUP *lookup, const char *file, int type); -// X509_load_crl_file loads CRLs from |file| and add them it to |lookup|'s -// |X509_STORE|. It returns one on success and zero on error. +// X509_load_crl_file loads CRLs from `file` and add them it to `lookup`'s +// `X509_STORE`. It returns one on success and zero on error. // -// If |type| is |X509_FILETYPE_ASN1|, it loads a single DER-encoded CRL. If -// |type| is |X509_FILETYPE_PEM|, it loads a sequence of PEM-encoded CRLs. -// |type| may not be |X509_FILETYPE_DEFAULT|. +// If `type` is `X509_FILETYPE_ASN1`, it loads a single DER-encoded CRL. If +// `type` is `X509_FILETYPE_PEM`, it loads a sequence of PEM-encoded CRLs. +// `type` may not be `X509_FILETYPE_DEFAULT`. OPENSSL_EXPORT int X509_load_crl_file(X509_LOOKUP *lookup, const char *file, int type); -// X509_load_cert_crl_file loads CRLs and trusted certificates from |file| and -// adds them to |lookup|'s |X509_STORE|. It returns one on success and zero on +// X509_load_cert_crl_file loads CRLs and trusted certificates from `file` and +// adds them to `lookup`'s `X509_STORE`. It returns one on success and zero on // error. // -// If |type| is |X509_FILETYPE_ASN1|, it loads a single DER-encoded certificate. -// This function cannot be used to load a DER-encoded CRL. If |type| is -// |X509_FILETYPE_PEM|, it loads a sequence of PEM-encoded certificates and -// CRLs. |type| may not be |X509_FILETYPE_DEFAULT|. +// If `type` is `X509_FILETYPE_ASN1`, it loads a single DER-encoded certificate. +// This function cannot be used to load a DER-encoded CRL. If `type` is +// `X509_FILETYPE_PEM`, it loads a sequence of PEM-encoded certificates and +// CRLs. `type` may not be `X509_FILETYPE_DEFAULT`. OPENSSL_EXPORT int X509_load_cert_crl_file(X509_LOOKUP *lookup, const char *file, int type); -// X509_NAME_hash returns a hash of |name|, or zero on error. This is the new -// hash used by |X509_LOOKUP_add_dir|. +// X509_NAME_hash returns a hash of `name`, or zero on error. This is the new +// hash used by `X509_LOOKUP_add_dir`. // -// This hash is specific to the |X509_LOOKUP_add_dir| filesystem format and is +// This hash is specific to the `X509_LOOKUP_add_dir` filesystem format and is // not suitable for general-purpose X.509 name processing. It is very short, so // there will be hash collisions. It also depends on an OpenSSL-specific // canonicalization process. OPENSSL_EXPORT uint32_t X509_NAME_hash(const X509_NAME *name); -// X509_NAME_hash_old returns a hash of |name|, or zero on error. This is the -// legacy hash used by |X509_LOOKUP_add_dir|, which is still supported for +// X509_NAME_hash_old returns a hash of `name`, or zero on error. This is the +// legacy hash used by `X509_LOOKUP_add_dir`, which is still supported for // compatibility. // -// This hash is specific to the |X509_LOOKUP_add_dir| filesystem format and is +// This hash is specific to the `X509_LOOKUP_add_dir` filesystem format and is // not suitable for general-purpose X.509 name processing. It is very short, so // there will be hash collisions. OPENSSL_EXPORT uint32_t X509_NAME_hash_old(const X509_NAME *name); -// X509_STORE_set_default_paths configures |store| to read from some "default" +// X509_STORE_set_default_paths configures `store` to read from some "default" // filesystem paths. It returns one on success and zero on error. The filesystem // paths are determined by a combination of hardcoded paths and the SSL_CERT_DIR // and SSL_CERT_FILE environment variables. @@ -3714,14 +3714,14 @@ // // The SignedPublicKeyAndChallenge (SPKAC) is a legacy structure to request // certificates, primarily in the legacy <keygen> HTML tag. An SPKAC structure -// is represented by a |NETSCAPE_SPKI| structure. +// is represented by a `NETSCAPE_SPKI` structure. // // The structure is described in // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/keygen -// A Netscape_spki_st, or |NETSCAPE_SPKI|, represents a +// A Netscape_spki_st, or `NETSCAPE_SPKI`, represents a // SignedPublicKeyAndChallenge structure. Although this structure contains a -// |spkac| field of type |NETSCAPE_SPKAC|, these are misnamed. The SPKAC is the +// `spkac` field of type `NETSCAPE_SPKAC`, these are misnamed. The SPKAC is the // entire structure, not the signed portion. struct Netscape_spki_st { NETSCAPE_SPKAC *spkac; @@ -3729,81 +3729,81 @@ ASN1_BIT_STRING *signature; } /* NETSCAPE_SPKI */; -// NETSCAPE_SPKI_new returns a newly-allocated, empty |NETSCAPE_SPKI| object, or +// NETSCAPE_SPKI_new returns a newly-allocated, empty `NETSCAPE_SPKI` object, or // NULL on error. OPENSSL_EXPORT NETSCAPE_SPKI *NETSCAPE_SPKI_new(void); -// NETSCAPE_SPKI_free releases memory associated with |spki|. +// NETSCAPE_SPKI_free releases memory associated with `spki`. OPENSSL_EXPORT void NETSCAPE_SPKI_free(NETSCAPE_SPKI *spki); -// d2i_NETSCAPE_SPKI parses up to |len| bytes from |*inp| as a DER-encoded -// SignedPublicKeyAndChallenge structure, as described in |d2i_SAMPLE|. +// d2i_NETSCAPE_SPKI parses up to `len` bytes from `*inp` as a DER-encoded +// SignedPublicKeyAndChallenge structure, as described in `d2i_SAMPLE`. OPENSSL_EXPORT NETSCAPE_SPKI *d2i_NETSCAPE_SPKI(NETSCAPE_SPKI **out, const uint8_t **inp, long len); -// i2d_NETSCAPE_SPKI marshals |spki| as a DER-encoded -// SignedPublicKeyAndChallenge structure, as described in |i2d_SAMPLE|. +// i2d_NETSCAPE_SPKI marshals `spki` as a DER-encoded +// SignedPublicKeyAndChallenge structure, as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_NETSCAPE_SPKI(const NETSCAPE_SPKI *spki, uint8_t **outp); -// NETSCAPE_SPKI_verify checks that |spki| has a valid signature by |pkey|. It +// NETSCAPE_SPKI_verify checks that `spki` has a valid signature by `pkey`. It // returns one if the signature is valid and zero otherwise. OPENSSL_EXPORT int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *spki, EVP_PKEY *pkey); -// NETSCAPE_SPKI_b64_decode decodes |len| bytes from |str| as a base64-encoded +// NETSCAPE_SPKI_b64_decode decodes `len` bytes from `str` as a base64-encoded // SignedPublicKeyAndChallenge structure. It returns a newly-allocated -// |NETSCAPE_SPKI| structure with the result, or NULL on error. If |len| is 0 or -// negative, the length is calculated with |strlen| and |str| must be a +// `NETSCAPE_SPKI` structure with the result, or NULL on error. If `len` is 0 or +// negative, the length is calculated with `strlen` and `str` must be a // NUL-terminated C string. OPENSSL_EXPORT NETSCAPE_SPKI *NETSCAPE_SPKI_b64_decode(const char *str, ossl_ssize_t len); -// NETSCAPE_SPKI_b64_encode encodes |spki| as a base64-encoded +// NETSCAPE_SPKI_b64_encode encodes `spki` as a base64-encoded // SignedPublicKeyAndChallenge structure. It returns a newly-allocated // NUL-terminated C string with the result, or NULL on error. The caller must -// release the memory with |OPENSSL_free| when done. +// release the memory with `OPENSSL_free` when done. OPENSSL_EXPORT char *NETSCAPE_SPKI_b64_encode(NETSCAPE_SPKI *spki); -// NETSCAPE_SPKI_get_pubkey decodes and returns the public key in |spki| as an -// |EVP_PKEY|, or NULL on error. The caller takes ownership of the resulting -// pointer and must call |EVP_PKEY_free| when done. +// NETSCAPE_SPKI_get_pubkey decodes and returns the public key in `spki` as an +// `EVP_PKEY`, or NULL on error. The caller takes ownership of the resulting +// pointer and must call `EVP_PKEY_free` when done. OPENSSL_EXPORT EVP_PKEY *NETSCAPE_SPKI_get_pubkey(const NETSCAPE_SPKI *spki); -// NETSCAPE_SPKI_set_pubkey sets |spki|'s public key to |pkey|. It returns one -// on success or zero on error. This function does not take ownership of |pkey|, -// so the caller may continue to manage its lifetime independently of |spki|. +// NETSCAPE_SPKI_set_pubkey sets `spki`'s public key to `pkey`. It returns one +// on success or zero on error. This function does not take ownership of `pkey`, +// so the caller may continue to manage its lifetime independently of `spki`. OPENSSL_EXPORT int NETSCAPE_SPKI_set_pubkey(NETSCAPE_SPKI *spki, EVP_PKEY *pkey); -// NETSCAPE_SPKI_sign signs |spki| with |pkey| and replaces the signature +// NETSCAPE_SPKI_sign signs `spki` with `pkey` and replaces the signature // algorithm and signature fields. It returns the length of the signature on -// success and zero on error. This function uses digest algorithm |md|, or -// |pkey|'s default if NULL. Other signing parameters use |pkey|'s defaults. +// success and zero on error. This function uses digest algorithm `md`, or +// `pkey`'s default if NULL. Other signing parameters use `pkey`'s defaults. OPENSSL_EXPORT int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *spki, EVP_PKEY *pkey, const EVP_MD *md); -// A Netscape_spkac_st, or |NETSCAPE_SPKAC|, represents a PublicKeyAndChallenge +// A Netscape_spkac_st, or `NETSCAPE_SPKAC`, represents a PublicKeyAndChallenge // structure. This type is misnamed. The full SPKAC includes the signature, -// which is represented with the |NETSCAPE_SPKI| type. +// which is represented with the `NETSCAPE_SPKI` type. struct Netscape_spkac_st { X509_PUBKEY *pubkey; ASN1_IA5STRING *challenge; } /* NETSCAPE_SPKAC */; -// NETSCAPE_SPKAC_new returns a newly-allocated, empty |NETSCAPE_SPKAC| object, +// NETSCAPE_SPKAC_new returns a newly-allocated, empty `NETSCAPE_SPKAC` object, // or NULL on error. OPENSSL_EXPORT NETSCAPE_SPKAC *NETSCAPE_SPKAC_new(void); -// NETSCAPE_SPKAC_free releases memory associated with |spkac|. +// NETSCAPE_SPKAC_free releases memory associated with `spkac`. OPENSSL_EXPORT void NETSCAPE_SPKAC_free(NETSCAPE_SPKAC *spkac); -// d2i_NETSCAPE_SPKAC parses up to |len| bytes from |*inp| as a DER-encoded -// PublicKeyAndChallenge structure, as described in |d2i_SAMPLE|. +// d2i_NETSCAPE_SPKAC parses up to `len` bytes from `*inp` as a DER-encoded +// PublicKeyAndChallenge structure, as described in `d2i_SAMPLE`. OPENSSL_EXPORT NETSCAPE_SPKAC *d2i_NETSCAPE_SPKAC(NETSCAPE_SPKAC **out, const uint8_t **inp, long len); -// i2d_NETSCAPE_SPKAC marshals |spkac| as a DER-encoded PublicKeyAndChallenge -// structure, as described in |i2d_SAMPLE|. +// i2d_NETSCAPE_SPKAC marshals `spkac` as a DER-encoded PublicKeyAndChallenge +// structure, as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_NETSCAPE_SPKAC(const NETSCAPE_SPKAC *spkac, uint8_t **outp); @@ -3816,43 +3816,43 @@ // discouraged. The parameters structure is very complex, and it takes more // bytes to merely encode parameters than an entire P-256 ECDSA signature. -// An rsa_pss_params_st, aka |RSA_PSS_PARAMS|, represents a parsed +// An rsa_pss_params_st, aka `RSA_PSS_PARAMS`, represents a parsed // RSASSA-PSS-params structure, as defined in (RFC 4055). struct rsa_pss_params_st { X509_ALGOR *hashAlgorithm; X509_ALGOR *maskGenAlgorithm; ASN1_INTEGER *saltLength; ASN1_INTEGER *trailerField; - // OpenSSL caches the MGF hash on |RSA_PSS_PARAMS| in some cases. None of the + // OpenSSL caches the MGF hash on `RSA_PSS_PARAMS` in some cases. None of the // cases apply to BoringSSL, so this is always NULL, but Node expects the // field to be present. X509_ALGOR *maskHash; } /* RSA_PSS_PARAMS */; -// RSA_PSS_PARAMS is an |ASN1_ITEM| whose ASN.1 type is RSASSA-PSS-params (RFC -// 4055) and C type is |RSA_PSS_PARAMS*|. +// RSA_PSS_PARAMS is an `ASN1_ITEM` whose ASN.1 type is RSASSA-PSS-params (RFC +// 4055) and C type is `RSA_PSS_PARAMS*`. DECLARE_ASN1_ITEM(RSA_PSS_PARAMS) -// RSA_PSS_PARAMS_new returns a new, empty |RSA_PSS_PARAMS|, or NULL on error. +// RSA_PSS_PARAMS_new returns a new, empty `RSA_PSS_PARAMS`, or NULL on error. OPENSSL_EXPORT RSA_PSS_PARAMS *RSA_PSS_PARAMS_new(void); -// RSA_PSS_PARAMS_free releases memory associated with |params|. +// RSA_PSS_PARAMS_free releases memory associated with `params`. OPENSSL_EXPORT void RSA_PSS_PARAMS_free(RSA_PSS_PARAMS *params); -// d2i_RSA_PSS_PARAMS parses up to |len| bytes from |*inp| as a DER-encoded -// RSASSA-PSS-params (RFC 4055), as described in |d2i_SAMPLE|. +// d2i_RSA_PSS_PARAMS parses up to `len` bytes from `*inp` as a DER-encoded +// RSASSA-PSS-params (RFC 4055), as described in `d2i_SAMPLE`. OPENSSL_EXPORT RSA_PSS_PARAMS *d2i_RSA_PSS_PARAMS(RSA_PSS_PARAMS **out, const uint8_t **inp, long len); -// i2d_RSA_PSS_PARAMS marshals |in| as a DER-encoded RSASSA-PSS-params (RFC -// 4055), as described in |i2d_SAMPLE|. +// i2d_RSA_PSS_PARAMS marshals `in` as a DER-encoded RSASSA-PSS-params (RFC +// 4055), as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_RSA_PSS_PARAMS(const RSA_PSS_PARAMS *in, uint8_t **outp); // PKCS#8 private keys. // -// The |PKCS8_PRIV_KEY_INFO| type represents a PKCS#8 PrivateKeyInfo (RFC 5208) +// The `PKCS8_PRIV_KEY_INFO` type represents a PKCS#8 PrivateKeyInfo (RFC 5208) // structure. This is analogous to SubjectPublicKeyInfo and uses the same // AlgorithmIdentifiers, but carries private keys and is not part of X.509 // itself. @@ -3860,68 +3860,68 @@ // TODO(davidben): Do these functions really belong in this header? // PKCS8_PRIV_KEY_INFO_new returns a newly-allocated, empty -// |PKCS8_PRIV_KEY_INFO| object, or NULL on error. +// `PKCS8_PRIV_KEY_INFO` object, or NULL on error. OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *PKCS8_PRIV_KEY_INFO_new(void); -// PKCS8_PRIV_KEY_INFO_free releases memory associated with |key|. +// PKCS8_PRIV_KEY_INFO_free releases memory associated with `key`. OPENSSL_EXPORT void PKCS8_PRIV_KEY_INFO_free(PKCS8_PRIV_KEY_INFO *key); -// d2i_PKCS8_PRIV_KEY_INFO parses up to |len| bytes from |*inp| as a DER-encoded -// PrivateKeyInfo, as described in |d2i_SAMPLE|. +// d2i_PKCS8_PRIV_KEY_INFO parses up to `len` bytes from `*inp` as a DER-encoded +// PrivateKeyInfo, as described in `d2i_SAMPLE`. OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *d2i_PKCS8_PRIV_KEY_INFO( PKCS8_PRIV_KEY_INFO **out, const uint8_t **inp, long len); -// i2d_PKCS8_PRIV_KEY_INFO marshals |key| as a DER-encoded PrivateKeyInfo, as -// described in |i2d_SAMPLE|. +// i2d_PKCS8_PRIV_KEY_INFO marshals `key` as a DER-encoded PrivateKeyInfo, as +// described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_PKCS8_PRIV_KEY_INFO(const PKCS8_PRIV_KEY_INFO *key, uint8_t **outp); -// EVP_PKCS82PKEY returns |p8| as a newly-allocated |EVP_PKEY|, or NULL if the +// EVP_PKCS82PKEY returns `p8` as a newly-allocated `EVP_PKEY`, or NULL if the // key was unsupported or could not be decoded. The caller must release the -// result with |EVP_PKEY_free| when done. +// result with `EVP_PKEY_free` when done. // -// Use |EVP_parse_private_key| instead. +// Use `EVP_parse_private_key` instead. OPENSSL_EXPORT EVP_PKEY *EVP_PKCS82PKEY(const PKCS8_PRIV_KEY_INFO *p8); -// EVP_PKEY2PKCS8 encodes |pkey| as a PKCS#8 PrivateKeyInfo (RFC 5208), -// represented as a newly-allocated |PKCS8_PRIV_KEY_INFO|, or NULL on error. The -// caller must release the result with |PKCS8_PRIV_KEY_INFO_free| when done. +// EVP_PKEY2PKCS8 encodes `pkey` as a PKCS#8 PrivateKeyInfo (RFC 5208), +// represented as a newly-allocated `PKCS8_PRIV_KEY_INFO`, or NULL on error. The +// caller must release the result with `PKCS8_PRIV_KEY_INFO_free` when done. // -// Use |EVP_marshal_private_key| instead. +// Use `EVP_marshal_private_key` instead. OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *EVP_PKEY2PKCS8(const EVP_PKEY *pkey); // Algorithm and octet string pairs. // -// The |X509_SIG| type represents an ASN.1 SEQUENCE type of an -// AlgorithmIdentifier and an OCTET STRING. Although named |X509_SIG|, there is +// The `X509_SIG` type represents an ASN.1 SEQUENCE type of an +// AlgorithmIdentifier and an OCTET STRING. Although named `X509_SIG`, there is // no type in X.509 which matches this format. The two common types which do are // DigestInfo (RFC 2315 and RFC 8017), and EncryptedPrivateKeyInfo (RFC 5208). -// X509_SIG_new returns a newly-allocated, empty |X509_SIG| object, or NULL on +// X509_SIG_new returns a newly-allocated, empty `X509_SIG` object, or NULL on // error. OPENSSL_EXPORT X509_SIG *X509_SIG_new(void); -// X509_SIG_free releases memory associated with |key|. +// X509_SIG_free releases memory associated with `key`. OPENSSL_EXPORT void X509_SIG_free(X509_SIG *key); -// d2i_X509_SIG parses up to |len| bytes from |*inp| as a DER-encoded algorithm -// and octet string pair, as described in |d2i_SAMPLE|. +// d2i_X509_SIG parses up to `len` bytes from `*inp` as a DER-encoded algorithm +// and octet string pair, as described in `d2i_SAMPLE`. OPENSSL_EXPORT X509_SIG *d2i_X509_SIG(X509_SIG **out, const uint8_t **inp, long len); -// i2d_X509_SIG marshals |sig| as a DER-encoded algorithm -// and octet string pair, as described in |i2d_SAMPLE|. +// i2d_X509_SIG marshals `sig` as a DER-encoded algorithm +// and octet string pair, as described in `i2d_SAMPLE`. OPENSSL_EXPORT int i2d_X509_SIG(const X509_SIG *sig, uint8_t **outp); -// X509_SIG_get0 sets |*out_alg| and |*out_digest| to non-owning pointers to -// |sig|'s algorithm and digest fields, respectively. Either |out_alg| and -// |out_digest| may be NULL to skip those fields. +// X509_SIG_get0 sets `*out_alg` and `*out_digest` to non-owning pointers to +// `sig`'s algorithm and digest fields, respectively. Either `out_alg` and +// `out_digest` may be NULL to skip those fields. OPENSSL_EXPORT void X509_SIG_get0(const X509_SIG *sig, const X509_ALGOR **out_alg, const ASN1_OCTET_STRING **out_digest); -// X509_SIG_getm behaves like |X509_SIG_get0| but returns mutable pointers. +// X509_SIG_getm behaves like `X509_SIG_get0` but returns mutable pointers. OPENSSL_EXPORT void X509_SIG_getm(X509_SIG *sig, X509_ALGOR **out_alg, ASN1_OCTET_STRING **out_digest); @@ -3933,8 +3933,8 @@ // and not parsed programmatically. In many cases, the outputs are ambiguous, so // attempting to parse them can lead to string injection vulnerabilities. -// The following flags control |X509_print_ex| and |X509_REQ_print_ex|. These -// flags co-exist with |X509V3_EXT_*|, so avoid collisions when adding new ones. +// The following flags control `X509_print_ex` and `X509_REQ_print_ex`. These +// flags co-exist with `X509V3_EXT_*`, so avoid collisions when adding new ones. // X509_FLAG_COMPAT disables all flags. It additionally causes names to be // printed with a 16-byte indent. @@ -3947,18 +3947,18 @@ #define X509_FLAG_NO_VERSION (1L << 1) // X509_FLAG_NO_SERIAL skips printing the serial number. It is ignored in -// |X509_REQ_print_fp|. +// `X509_REQ_print_fp`. #define X509_FLAG_NO_SERIAL (1L << 2) // X509_FLAG_NO_SIGNAME skips printing the signature algorithm in the -// TBSCertificate. It is ignored in |X509_REQ_print_fp|. +// TBSCertificate. It is ignored in `X509_REQ_print_fp`. #define X509_FLAG_NO_SIGNAME (1L << 3) // X509_FLAG_NO_ISSUER skips printing the issuer. #define X509_FLAG_NO_ISSUER (1L << 4) // X509_FLAG_NO_VALIDITY skips printing the notBefore and notAfter times. It is -// ignored in |X509_REQ_print_fp|. +// ignored in `X509_REQ_print_fp`. #define X509_FLAG_NO_VALIDITY (1L << 5) // X509_FLAG_NO_SUBJECT skips printing the subject. @@ -3968,15 +3968,15 @@ #define X509_FLAG_NO_PUBKEY (1L << 7) // X509_FLAG_NO_EXTENSIONS skips printing the extension list. It is ignored in -// |X509_REQ_print_fp|. CSRs instead have attributes, which is controlled by -// |X509_FLAG_NO_ATTRIBUTES|. +// `X509_REQ_print_fp`. CSRs instead have attributes, which is controlled by +// `X509_FLAG_NO_ATTRIBUTES`. #define X509_FLAG_NO_EXTENSIONS (1L << 8) // X509_FLAG_NO_SIGDUMP skips printing the signature and outer signature // algorithm. #define X509_FLAG_NO_SIGDUMP (1L << 9) -// X509_FLAG_NO_AUX skips printing auxiliary properties. (See |d2i_X509_AUX| and +// X509_FLAG_NO_AUX skips printing auxiliary properties. (See `d2i_X509_AUX` and // related functions.) #define X509_FLAG_NO_AUX (1L << 10) @@ -3985,12 +3985,12 @@ #define X509_FLAG_NO_ATTRIBUTES (1L << 11) // X509_FLAG_NO_IDS skips printing the issuerUniqueID and subjectUniqueID in a -// certificate. It is ignored in |X509_REQ_print_fp|. +// certificate. It is ignored in `X509_REQ_print_fp`. #define X509_FLAG_NO_IDS (1L << 12) -// The following flags control |X509_print_ex|, |X509_REQ_print_ex|, -// |X509V3_EXT_print|, and |X509V3_extensions_print|. These flags coexist with -// |X509_FLAG_*|, so avoid collisions when adding new ones. +// The following flags control `X509_print_ex`, `X509_REQ_print_ex`, +// `X509V3_EXT_print`, and `X509V3_extensions_print`. These flags coexist with +// `X509_FLAG_*`, so avoid collisions when adding new ones. // X509V3_EXT_UNKNOWN_MASK is a mask that determines how unknown extensions are // processed. @@ -4005,59 +4005,59 @@ #define X509V3_EXT_ERROR_UNKNOWN (1L << 16) // X509V3_EXT_PARSE_UNKNOWN is deprecated and behaves like -// |X509V3_EXT_DUMP_UNKNOWN|. +// `X509V3_EXT_DUMP_UNKNOWN`. #define X509V3_EXT_PARSE_UNKNOWN (2L << 16) // X509V3_EXT_DUMP_UNKNOWN causes unknown extensions to be displayed as a // hexdump. #define X509V3_EXT_DUMP_UNKNOWN (3L << 16) -// X509_print_ex writes a human-readable representation of |x| to |bp|. It -// returns one on success and zero on error. |nmflags| is the flags parameter -// for |X509_NAME_print_ex| when printing the subject and issuer. |cflag| should -// be some combination of the |X509_FLAG_*| and |X509V3_EXT_*| constants. +// X509_print_ex writes a human-readable representation of `x` to `bp`. It +// returns one on success and zero on error. `nmflags` is the flags parameter +// for `X509_NAME_print_ex` when printing the subject and issuer. `cflag` should +// be some combination of the `X509_FLAG_*` and `X509V3_EXT_*` constants. OPENSSL_EXPORT int X509_print_ex(BIO *bp, const X509 *x, unsigned long nmflag, unsigned long cflag); -// X509_print_ex_fp behaves like |X509_print_ex| but writes to |fp|. +// X509_print_ex_fp behaves like `X509_print_ex` but writes to `fp`. OPENSSL_EXPORT int X509_print_ex_fp(FILE *fp, const X509 *x, unsigned long nmflag, unsigned long cflag); -// X509_print calls |X509_print_ex| with |XN_FLAG_COMPAT| and |X509_FLAG_COMPAT| +// X509_print calls `X509_print_ex` with `XN_FLAG_COMPAT` and `X509_FLAG_COMPAT` // flags. OPENSSL_EXPORT int X509_print(BIO *bp, const X509 *x); -// X509_print_fp behaves like |X509_print| but writes to |fp|. +// X509_print_fp behaves like `X509_print` but writes to `fp`. OPENSSL_EXPORT int X509_print_fp(FILE *fp, const X509 *x); -// X509_CRL_print writes a human-readable representation of |x| to |bp|. It +// X509_CRL_print writes a human-readable representation of `x` to `bp`. It // returns one on success and zero on error. OPENSSL_EXPORT int X509_CRL_print(BIO *bp, const X509_CRL *x); -// X509_CRL_print_fp behaves like |X509_CRL_print| but writes to |fp|. +// X509_CRL_print_fp behaves like `X509_CRL_print` but writes to `fp`. OPENSSL_EXPORT int X509_CRL_print_fp(FILE *fp, const X509_CRL *x); -// X509_REQ_print_ex writes a human-readable representation of |x| to |bp|. It -// returns one on success and zero on error. |nmflags| is the flags parameter -// for |X509_NAME_print_ex|, when printing the subject. |cflag| should be some -// combination of the |X509_FLAG_*| and |X509V3_EXT_*| constants. +// X509_REQ_print_ex writes a human-readable representation of `x` to `bp`. It +// returns one on success and zero on error. `nmflags` is the flags parameter +// for `X509_NAME_print_ex`, when printing the subject. `cflag` should be some +// combination of the `X509_FLAG_*` and `X509V3_EXT_*` constants. OPENSSL_EXPORT int X509_REQ_print_ex(BIO *bp, const X509_REQ *x, unsigned long nmflag, unsigned long cflag); -// X509_REQ_print calls |X509_REQ_print_ex| with |XN_FLAG_COMPAT| and -// |X509_FLAG_COMPAT| flags. +// X509_REQ_print calls `X509_REQ_print_ex` with `XN_FLAG_COMPAT` and +// `X509_FLAG_COMPAT` flags. OPENSSL_EXPORT int X509_REQ_print(BIO *bp, const X509_REQ *req); -// X509_REQ_print_fp behaves like |X509_REQ_print| but writes to |fp|. +// X509_REQ_print_fp behaves like `X509_REQ_print` but writes to `fp`. OPENSSL_EXPORT int X509_REQ_print_fp(FILE *fp, const X509_REQ *req); -// The following flags are control |X509_NAME_print_ex|. They must not collide -// with |ASN1_STRFLGS_*|. +// The following flags are control `X509_NAME_print_ex`. They must not collide +// with `ASN1_STRFLGS_*`. // // TODO(davidben): This is far, far too many options and most of them are // useless. Trim this down. -// XN_FLAG_COMPAT prints with |X509_NAME_print|'s format and return value +// XN_FLAG_COMPAT prints with `X509_NAME_print`'s format and return value // convention. #define XN_FLAG_COMPAT 0ul @@ -4068,7 +4068,7 @@ // with "+", as in RFC 2253. #define XN_FLAG_SEP_COMMA_PLUS (1ul << 16) -// XN_FLAG_SEP_CPLUS_SPC behaves like |XN_FLAG_SEP_COMMA_PLUS| but adds spaces +// XN_FLAG_SEP_CPLUS_SPC behaves like `XN_FLAG_SEP_COMMA_PLUS` but adds spaces // between the separators. #define XN_FLAG_SEP_CPLUS_SPC (2ul << 16) @@ -4106,62 +4106,62 @@ (ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | \ XN_FLAG_SPC_EQ | XN_FLAG_FN_SN) -// X509_NAME_print_ex writes a human-readable representation of |nm| to |out|. -// Each line of output is indented by |indent| spaces. It returns the number of -// bytes written on success, and -1 on error. If |out| is NULL, it returns the -// number of bytes it would have written but does not write anything. |flags| -// should be some combination of |XN_FLAG_*| and |ASN1_STRFLGS_*| values and -// determines the output. If unsure, use |XN_FLAG_RFC2253|. +// X509_NAME_print_ex writes a human-readable representation of `nm` to `out`. +// Each line of output is indented by `indent` spaces. It returns the number of +// bytes written on success, and -1 on error. If `out` is NULL, it returns the +// number of bytes it would have written but does not write anything. `flags` +// should be some combination of `XN_FLAG_*` and `ASN1_STRFLGS_*` values and +// determines the output. If unsure, use `XN_FLAG_RFC2253`. // -// If |flags| is |XN_FLAG_COMPAT|, or zero, this function calls -// |X509_NAME_print| instead. In that case, it returns one on success, rather +// If `flags` is `XN_FLAG_COMPAT`, or zero, this function calls +// `X509_NAME_print` instead. In that case, it returns one on success, rather // than the output length. OPENSSL_EXPORT int X509_NAME_print_ex(BIO *out, const X509_NAME *nm, int indent, unsigned long flags); -// X509_NAME_print prints a human-readable representation of |name| to |bp|. It -// returns one on success and zero on error. |obase| is ignored. +// X509_NAME_print prints a human-readable representation of `name` to `bp`. It +// returns one on success and zero on error. `obase` is ignored. // // This function outputs a legacy format that does not correctly handle string -// encodings and other cases. Prefer |X509_NAME_print_ex| if printing a name for +// encodings and other cases. Prefer `X509_NAME_print_ex` if printing a name for // debugging purposes. OPENSSL_EXPORT int X509_NAME_print(BIO *bp, const X509_NAME *name, int obase); -// X509_NAME_oneline writes a human-readable representation to |name| to a +// X509_NAME_oneline writes a human-readable representation to `name` to a // buffer as a NUL-terminated C string. // -// If |buf| is NULL, returns a newly-allocated buffer containing the result on -// success, or NULL on error. The buffer must be released with |OPENSSL_free| +// If `buf` is NULL, returns a newly-allocated buffer containing the result on +// success, or NULL on error. The buffer must be released with `OPENSSL_free` // when done. // -// If |buf| is non-NULL, at most |size| bytes of output are written to |buf| -// instead. |size| includes the trailing NUL. The function then returns |buf| on -// success or NULL on error. If the output does not fit in |size| bytes, the +// If `buf` is non-NULL, at most `size` bytes of output are written to `buf` +// instead. `size` includes the trailing NUL. The function then returns `buf` on +// success or NULL on error. If the output does not fit in `size` bytes, the // output is silently truncated at an attribute boundary. // // This function outputs a legacy format that does not correctly handle string -// encodings and other cases. Prefer |X509_NAME_print_ex| if printing a name for +// encodings and other cases. Prefer `X509_NAME_print_ex` if printing a name for // debugging purposes. OPENSSL_EXPORT char *X509_NAME_oneline(const X509_NAME *name, char *buf, int size); -// X509_NAME_print_ex_fp behaves like |X509_NAME_print_ex| but writes to |fp|. +// X509_NAME_print_ex_fp behaves like `X509_NAME_print_ex` but writes to `fp`. OPENSSL_EXPORT int X509_NAME_print_ex_fp(FILE *fp, const X509_NAME *nm, int indent, unsigned long flags); -// X509_signature_dump writes a human-readable representation of |sig| to |bio|, -// indented with |indent| spaces. It returns one on success and zero on error. +// X509_signature_dump writes a human-readable representation of `sig` to `bio`, +// indented with `indent` spaces. It returns one on success and zero on error. OPENSSL_EXPORT int X509_signature_dump(BIO *bio, const ASN1_STRING *sig, int indent); -// X509_signature_print writes a human-readable representation of |alg| and -// |sig| to |bio|. It returns one on success and zero on error. +// X509_signature_print writes a human-readable representation of `alg` and +// `sig` to `bio`. It returns one on success and zero on error. OPENSSL_EXPORT int X509_signature_print(BIO *bio, const X509_ALGOR *alg, const ASN1_STRING *sig); -// X509V3_EXT_print prints a human-readable representation of |ext| to out. It -// returns one on success and zero on error. The output is indented by |indent| -// spaces. |flag| is one of the |X509V3_EXT_*| constants and controls printing +// X509V3_EXT_print prints a human-readable representation of `ext` to out. It +// returns one on success and zero on error. The output is indented by `indent` +// spaces. `flag` is one of the `X509V3_EXT_*` constants and controls printing // of unknown extensions and syntax errors. // // WARNING: Although some applications programmatically parse the output of this @@ -4172,21 +4172,21 @@ OPENSSL_EXPORT int X509V3_EXT_print(BIO *out, const X509_EXTENSION *ext, unsigned long flag, int indent); -// X509V3_EXT_print_fp behaves like |X509V3_EXT_print| but writes to a |FILE| -// instead of a |BIO|. +// X509V3_EXT_print_fp behaves like `X509V3_EXT_print` but writes to a `FILE` +// instead of a `BIO`. OPENSSL_EXPORT int X509V3_EXT_print_fp(FILE *out, const X509_EXTENSION *ext, int flag, int indent); -// X509V3_extensions_print prints |title|, followed by a human-readable -// representation of |exts| to |out|. It returns one on success and zero on -// error. The output is indented by |indent| spaces. |flag| is one of the -// |X509V3_EXT_*| constants and controls printing of unknown extensions and +// X509V3_extensions_print prints `title`, followed by a human-readable +// representation of `exts` to `out`. It returns one on success and zero on +// error. The output is indented by `indent` spaces. `flag` is one of the +// `X509V3_EXT_*` constants and controls printing of unknown extensions and // syntax errors. OPENSSL_EXPORT int X509V3_extensions_print(BIO *out, const char *title, const STACK_OF(X509_EXTENSION) *exts, unsigned long flag, int indent); -// GENERAL_NAME_print prints a human-readable representation of |gen| to |out|. +// GENERAL_NAME_print prints a human-readable representation of `gen` to `out`. // It returns one on success and zero on error. // // TODO(davidben): Actually, it just returns one and doesn't check for I/O or @@ -4196,10 +4196,10 @@ // Convenience functions. -// X509_pubkey_digest hashes the contents of the BIT STRING in |x509|'s -// subjectPublicKeyInfo field with |md| and writes the result to |out|. -// |EVP_MD_CTX_size| bytes are written, which is at most |EVP_MAX_MD_SIZE|. If -// |out_len| is not NULL, |*out_len| is set to the number of bytes written. This +// X509_pubkey_digest hashes the contents of the BIT STRING in `x509`'s +// subjectPublicKeyInfo field with `md` and writes the result to `out`. +// `EVP_MD_CTX_size` bytes are written, which is at most `EVP_MAX_MD_SIZE`. If +// `out_len` is not NULL, `*out_len` is set to the number of bytes written. This // function returns one on success and zero on error. // // This hash omits the BIT STRING tag, length, and number of unused bits. It @@ -4209,42 +4209,42 @@ OPENSSL_EXPORT int X509_pubkey_digest(const X509 *x509, const EVP_MD *md, uint8_t *out, unsigned *out_len); -// X509_digest hashes |x509|'s DER encoding with |md| and writes the result to -// |out|. |EVP_MD_CTX_size| bytes are written, which is at most -// |EVP_MAX_MD_SIZE|. If |out_len| is not NULL, |*out_len| is set to the number +// X509_digest hashes `x509`'s DER encoding with `md` and writes the result to +// `out`. `EVP_MD_CTX_size` bytes are written, which is at most +// `EVP_MAX_MD_SIZE`. If `out_len` is not NULL, `*out_len` is set to the number // of bytes written. This function returns one on success and zero on error. // Note this digest covers the entire certificate, not just the signed portion. OPENSSL_EXPORT int X509_digest(const X509 *x509, const EVP_MD *md, uint8_t *out, unsigned *out_len); -// X509_CRL_digest hashes |crl|'s DER encoding with |md| and writes the result -// to |out|. |EVP_MD_CTX_size| bytes are written, which is at most -// |EVP_MAX_MD_SIZE|. If |out_len| is not NULL, |*out_len| is set to the number +// X509_CRL_digest hashes `crl`'s DER encoding with `md` and writes the result +// to `out`. `EVP_MD_CTX_size` bytes are written, which is at most +// `EVP_MAX_MD_SIZE`. If `out_len` is not NULL, `*out_len` is set to the number // of bytes written. This function returns one on success and zero on error. // Note this digest covers the entire CRL, not just the signed portion. OPENSSL_EXPORT int X509_CRL_digest(const X509_CRL *crl, const EVP_MD *md, uint8_t *out, unsigned *out_len); -// X509_REQ_digest hashes |req|'s DER encoding with |md| and writes the result -// to |out|. |EVP_MD_CTX_size| bytes are written, which is at most -// |EVP_MAX_MD_SIZE|. If |out_len| is not NULL, |*out_len| is set to the number +// X509_REQ_digest hashes `req`'s DER encoding with `md` and writes the result +// to `out`. `EVP_MD_CTX_size` bytes are written, which is at most +// `EVP_MAX_MD_SIZE`. If `out_len` is not NULL, `*out_len` is set to the number // of bytes written. This function returns one on success and zero on error. // Note this digest covers the entire certificate request, not just the signed // portion. OPENSSL_EXPORT int X509_REQ_digest(const X509_REQ *req, const EVP_MD *md, uint8_t *out, unsigned *out_len); -// X509_NAME_digest hashes |name|'s DER encoding with |md| and writes the result -// to |out|. |EVP_MD_CTX_size| bytes are written, which is at most -// |EVP_MAX_MD_SIZE|. If |out_len| is not NULL, |*out_len| is set to the number +// X509_NAME_digest hashes `name`'s DER encoding with `md` and writes the result +// to `out`. `EVP_MD_CTX_size` bytes are written, which is at most +// `EVP_MAX_MD_SIZE`. If `out_len` is not NULL, `*out_len` is set to the number // of bytes written. This function returns one on success and zero on error. OPENSSL_EXPORT int X509_NAME_digest(const X509_NAME *name, const EVP_MD *md, uint8_t *out, unsigned *out_len); -// The following functions behave like the corresponding unsuffixed |d2i_*| -// functions, but read the result from |bp| instead. Callers using these -// functions with memory |BIO|s to parse structures already in memory should use -// |d2i_*| instead. +// The following functions behave like the corresponding unsuffixed `d2i_*` +// functions, but read the result from `bp` instead. Callers using these +// functions with memory `BIO`s to parse structures already in memory should use +// `d2i_*` instead. OPENSSL_EXPORT X509 *d2i_X509_bio(BIO *bp, X509 **x509); OPENSSL_EXPORT X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **crl); OPENSSL_EXPORT X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **req); @@ -4261,14 +4261,14 @@ OPENSSL_EXPORT EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a); OPENSSL_EXPORT DH *d2i_DHparams_bio(BIO *bp, DH **dh); -// d2i_PrivateKey_bio behaves like |d2i_AutoPrivateKey|, but reads from |bp| +// d2i_PrivateKey_bio behaves like `d2i_AutoPrivateKey`, but reads from `bp` // instead. OPENSSL_EXPORT EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a); -// The following functions behave like the corresponding unsuffixed |i2d_*| -// functions, but write the result to |bp|. They return one on success and zero -// on error. Callers using them with memory |BIO|s to encode structures to -// memory should use |i2d_*| directly instead. +// The following functions behave like the corresponding unsuffixed `i2d_*` +// functions, but write the result to `bp`. They return one on success and zero +// on error. Callers using them with memory `BIO`s to encode structures to +// memory should use `i2d_*` directly instead. OPENSSL_EXPORT int i2d_X509_bio(BIO *bp, const X509 *x509); OPENSSL_EXPORT int i2d_X509_CRL_bio(BIO *bp, const X509_CRL *crl); OPENSSL_EXPORT int i2d_X509_REQ_bio(BIO *bp, const X509_REQ *req); @@ -4286,13 +4286,13 @@ OPENSSL_EXPORT int i2d_PUBKEY_bio(BIO *bp, const EVP_PKEY *pkey); OPENSSL_EXPORT int i2d_DHparams_bio(BIO *bp, const DH *dh); -// i2d_PKCS8PrivateKeyInfo_bio encodes |key| as a PKCS#8 PrivateKeyInfo -// structure (see |EVP_marshal_private_key|) and writes the result to |bp|. It +// i2d_PKCS8PrivateKeyInfo_bio encodes `key` as a PKCS#8 PrivateKeyInfo +// structure (see `EVP_marshal_private_key`) and writes the result to `bp`. It // returns one on success and zero on error. OPENSSL_EXPORT int i2d_PKCS8PrivateKeyInfo_bio(BIO *bp, const EVP_PKEY *key); -// The following functions behave like the corresponding |d2i_*_bio| functions, -// but read from |fp| instead. +// The following functions behave like the corresponding `d2i_*_bio` functions, +// but read from `fp` instead. OPENSSL_EXPORT X509 *d2i_X509_fp(FILE *fp, X509 **x509); OPENSSL_EXPORT X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **crl); OPENSSL_EXPORT X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **req); @@ -4309,8 +4309,8 @@ OPENSSL_EXPORT EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a); OPENSSL_EXPORT EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a); -// The following functions behave like the corresponding |i2d_*_bio| functions, -// but write to |fp| instead. +// The following functions behave like the corresponding `i2d_*_bio` functions, +// but write to `fp` instead. OPENSSL_EXPORT int i2d_X509_fp(FILE *fp, const X509 *x509); OPENSSL_EXPORT int i2d_X509_CRL_fp(FILE *fp, const X509_CRL *crl); OPENSSL_EXPORT int i2d_X509_REQ_fp(FILE *fp, const X509_REQ *req); @@ -4328,96 +4328,96 @@ OPENSSL_EXPORT int i2d_PrivateKey_fp(FILE *fp, const EVP_PKEY *pkey); OPENSSL_EXPORT int i2d_PUBKEY_fp(FILE *fp, const EVP_PKEY *pkey); -// X509_find_by_issuer_and_serial returns the first |X509| in |sk| whose issuer -// and serial are |name| and |serial|, respectively. If no match is found, it +// X509_find_by_issuer_and_serial returns the first `X509` in `sk` whose issuer +// and serial are `name` and `serial`, respectively. If no match is found, it // returns NULL. OPENSSL_EXPORT X509 *X509_find_by_issuer_and_serial(const STACK_OF(X509) *sk, const X509_NAME *name, const ASN1_INTEGER *serial); -// X509_find_by_subject returns the first |X509| in |sk| whose subject is -// |name|. If no match is found, it returns NULL. +// X509_find_by_subject returns the first `X509` in `sk` whose subject is +// `name`. If no match is found, it returns NULL. OPENSSL_EXPORT X509 *X509_find_by_subject(const STACK_OF(X509) *sk, const X509_NAME *name); -// X509_cmp_time compares |s| against |*t|. On success, it returns a negative -// number if |s| <= |*t| and a positive number if |s| > |*t|. On error, it -// returns zero. If |t| is NULL, it uses the current time instead of |*t|. +// X509_cmp_time compares `s` against `*t`. On success, it returns a negative +// number if `s` <= `*t` and a positive number if `s` > `*t`. On error, it +// returns zero. If `t` is NULL, it uses the current time instead of `*t`. // // WARNING: Unlike most comparison functions, this function returns zero on // error, not equality. OPENSSL_EXPORT int X509_cmp_time(const ASN1_TIME *s, const time_t *t); -// X509_cmp_time_posix compares |s| against |t|. On success, it returns a -// negative number if |s| <= |t| and a positive number if |s| > |t|. On error, +// X509_cmp_time_posix compares `s` against `t`. On success, it returns a +// negative number if `s` <= `t` and a positive number if `s` > `t`. On error, // it returns zero. // // WARNING: Unlike most comparison functions, this function returns zero on // error, not equality. OPENSSL_EXPORT int X509_cmp_time_posix(const ASN1_TIME *s, int64_t t); -// X509_cmp_current_time behaves like |X509_cmp_time| but compares |s| against +// X509_cmp_current_time behaves like `X509_cmp_time` but compares `s` against // the current time. OPENSSL_EXPORT int X509_cmp_current_time(const ASN1_TIME *s); -// X509_time_adj calls |X509_time_adj_ex| with |offset_day| equal to zero. +// X509_time_adj calls `X509_time_adj_ex` with `offset_day` equal to zero. OPENSSL_EXPORT ASN1_TIME *X509_time_adj(ASN1_TIME *s, long offset_sec, const time_t *t); -// X509_time_adj_ex behaves like |ASN1_TIME_adj|, but adds an offset to |*t|. If -// |t| is NULL, it uses the current time instead of |*t|. +// X509_time_adj_ex behaves like `ASN1_TIME_adj`, but adds an offset to `*t`. If +// `t` is NULL, it uses the current time instead of `*t`. OPENSSL_EXPORT ASN1_TIME *X509_time_adj_ex(ASN1_TIME *s, int offset_day, long offset_sec, const time_t *t); -// X509_gmtime_adj behaves like |X509_time_adj_ex| but adds |offset_sec| to the +// X509_gmtime_adj behaves like `X509_time_adj_ex` but adds `offset_sec` to the // current time. OPENSSL_EXPORT ASN1_TIME *X509_gmtime_adj(ASN1_TIME *s, long offset_sec); -// X509_issuer_name_cmp behaves like |X509_NAME_cmp|, but compares |a| and |b|'s +// X509_issuer_name_cmp behaves like `X509_NAME_cmp`, but compares `a` and `b`'s // issuer names. OPENSSL_EXPORT int X509_issuer_name_cmp(const X509 *a, const X509 *b); -// X509_subject_name_cmp behaves like |X509_NAME_cmp|, but compares |a| and -// |b|'s subject names. +// X509_subject_name_cmp behaves like `X509_NAME_cmp`, but compares `a` and +// `b`'s subject names. OPENSSL_EXPORT int X509_subject_name_cmp(const X509 *a, const X509 *b); -// X509_CRL_cmp behaves like |X509_NAME_cmp|, but compares |a| and |b|'s +// X509_CRL_cmp behaves like `X509_NAME_cmp`, but compares `a` and `b`'s // issuer names. // // WARNING: This function is misnamed. It does not compare other parts of the -// CRL, only the issuer fields using |X509_NAME_cmp|. +// CRL, only the issuer fields using `X509_NAME_cmp`. OPENSSL_EXPORT int X509_CRL_cmp(const X509_CRL *a, const X509_CRL *b); -// X509_issuer_name_hash returns the hash of |x509|'s issuer name with -// |X509_NAME_hash|. +// X509_issuer_name_hash returns the hash of `x509`'s issuer name with +// `X509_NAME_hash`. // -// This hash is specific to the |X509_LOOKUP_add_dir| filesystem format and is +// This hash is specific to the `X509_LOOKUP_add_dir` filesystem format and is // not suitable for general-purpose X.509 name processing. It is very short, so // there will be hash collisions. It also depends on an OpenSSL-specific // canonicalization process. OPENSSL_EXPORT uint32_t X509_issuer_name_hash(const X509 *x509); -// X509_subject_name_hash returns the hash of |x509|'s subject name with -// |X509_NAME_hash|. +// X509_subject_name_hash returns the hash of `x509`'s subject name with +// `X509_NAME_hash`. // -// This hash is specific to the |X509_LOOKUP_add_dir| filesystem format and is +// This hash is specific to the `X509_LOOKUP_add_dir` filesystem format and is // not suitable for general-purpose X.509 name processing. It is very short, so // there will be hash collisions. It also depends on an OpenSSL-specific // canonicalization process. OPENSSL_EXPORT uint32_t X509_subject_name_hash(const X509 *x509); -// X509_issuer_name_hash_old returns the hash of |x509|'s issuer name with -// |X509_NAME_hash_old|. +// X509_issuer_name_hash_old returns the hash of `x509`'s issuer name with +// `X509_NAME_hash_old`. // -// This hash is specific to the |X509_LOOKUP_add_dir| filesystem format and is +// This hash is specific to the `X509_LOOKUP_add_dir` filesystem format and is // not suitable for general-purpose X.509 name processing. It is very short, so // there will be hash collisions. OPENSSL_EXPORT uint32_t X509_issuer_name_hash_old(const X509 *x509); -// X509_subject_name_hash_old returns the hash of |x509|'s usjbect name with -// |X509_NAME_hash_old|. +// X509_subject_name_hash_old returns the hash of `x509`'s usjbect name with +// `X509_NAME_hash_old`. // -// This hash is specific to the |X509_LOOKUP_add_dir| filesystem format and is +// This hash is specific to the `X509_LOOKUP_add_dir` filesystem format and is // not suitable for general-purpose X.509 name processing. It is very short, so // there will be hash collisions. OPENSSL_EXPORT uint32_t X509_subject_name_hash_old(const X509 *x509); @@ -4425,7 +4425,7 @@ // ex_data functions. // -// See |ex_data.h| for details. +// See `ex_data.h` for details. OPENSSL_EXPORT int X509_get_ex_new_index(long argl, void *argp, CRYPTO_EX_unused *unused, @@ -4449,70 +4449,70 @@ // Hashing and signing ASN.1 structures. -// ASN1_digest serializes |data| with |i2d| and then hashes the result with -// |type|. On success, it returns one, writes the digest to |md|, and sets -// |*len| to the digest length if non-NULL. On error, it returns zero. +// ASN1_digest serializes `data` with `i2d` and then hashes the result with +// `type`. On success, it returns one, writes the digest to `md`, and sets +// `*len` to the digest length if non-NULL. On error, it returns zero. // -// |EVP_MD_CTX_size| bytes are written, which is at most |EVP_MAX_MD_SIZE|. The +// `EVP_MD_CTX_size` bytes are written, which is at most `EVP_MAX_MD_SIZE`. The // buffer must have sufficient space for this output. OPENSSL_EXPORT int ASN1_digest(i2d_of_void *i2d, const EVP_MD *type, char *data, unsigned char *md, unsigned int *len); -// ASN1_item_digest serializes |data| with |it| and then hashes the result with -// |type|. On success, it returns one, writes the digest to |md|, and sets -// |*len| to the digest length if non-NULL. On error, it returns zero. +// ASN1_item_digest serializes `data` with `it` and then hashes the result with +// `type`. On success, it returns one, writes the digest to `md`, and sets +// `*len` to the digest length if non-NULL. On error, it returns zero. // -// |EVP_MD_CTX_size| bytes are written, which is at most |EVP_MAX_MD_SIZE|. The +// `EVP_MD_CTX_size` bytes are written, which is at most `EVP_MAX_MD_SIZE`. The // buffer must have sufficient space for this output. // -// WARNING: |data| must be a pointer with the same type as |it|'s corresponding +// WARNING: `data` must be a pointer with the same type as `it`'s corresponding // C type. Using the wrong type is a potentially exploitable memory error. OPENSSL_EXPORT int ASN1_item_digest(const ASN1_ITEM *it, const EVP_MD *type, void *data, unsigned char *md, unsigned int *len); -// ASN1_item_verify serializes |data| with |it| and then verifies |signature| is -// a valid signature for the result with |algor1| and |pkey|. It returns one on +// ASN1_item_verify serializes `data` with `it` and then verifies `signature` is +// a valid signature for the result with `algor1` and `pkey`. It returns one on // success and zero on error. The signature and algorithm are interpreted as in // X.509. // -// WARNING: |data| must be a pointer with the same type as |it|'s corresponding +// WARNING: `data` must be a pointer with the same type as `it`'s corresponding // C type. Using the wrong type is a potentially exploitable memory error. OPENSSL_EXPORT int ASN1_item_verify(const ASN1_ITEM *it, const X509_ALGOR *algor1, const ASN1_BIT_STRING *signature, void *data, EVP_PKEY *pkey); -// ASN1_item_sign serializes |data| with |it| and then signs the result with -// the private key |pkey|. It returns the length of the signature on success and -// zero on error. On success, it writes the signature to |signature| and the -// signature algorithm to each of |algor1| and |algor2|. Either of |algor1| or -// |algor2| may be NULL to ignore them. This function uses digest algorithm -// |md|, or |pkey|'s default if NULL. Other signing parameters use |pkey|'s -// defaults. To customize them, use |ASN1_item_sign_ctx|. +// ASN1_item_sign serializes `data` with `it` and then signs the result with +// the private key `pkey`. It returns the length of the signature on success and +// zero on error. On success, it writes the signature to `signature` and the +// signature algorithm to each of `algor1` and `algor2`. Either of `algor1` or +// `algor2` may be NULL to ignore them. This function uses digest algorithm +// `md`, or `pkey`'s default if NULL. Other signing parameters use `pkey`'s +// defaults. To customize them, use `ASN1_item_sign_ctx`. // -// |algor1| and |algor2| may point into part of |asn| and will be updated before -// |asn| is serialized. +// `algor1` and `algor2` may point into part of `asn` and will be updated before +// `asn` is serialized. // -// WARNING: |data| must be a pointer with the same type as |it|'s corresponding +// WARNING: `data` must be a pointer with the same type as `it`'s corresponding // C type. Using the wrong type is a potentially exploitable memory error. OPENSSL_EXPORT int ASN1_item_sign(const ASN1_ITEM *it, X509_ALGOR *algor1, X509_ALGOR *algor2, ASN1_BIT_STRING *signature, void *data, EVP_PKEY *pkey, const EVP_MD *type); -// ASN1_item_sign_ctx behaves like |ASN1_item_sign| except the signature is -// signed with |ctx|, |ctx|, which must have been initialized with -// |EVP_DigestSignInit|. The caller should configure the corresponding -// |EVP_PKEY_CTX| with any additional parameters before calling this function. +// ASN1_item_sign_ctx behaves like `ASN1_item_sign` except the signature is +// signed with `ctx`, `ctx`, which must have been initialized with +// `EVP_DigestSignInit`. The caller should configure the corresponding +// `EVP_PKEY_CTX` with any additional parameters before calling this function. // -// On success or failure, this function mutates |ctx| and resets it to the empty +// On success or failure, this function mutates `ctx` and resets it to the empty // state. Caller should not rely on its contents after the function returns. // -// |algor1| and |algor2| may point into part of |asn| and will be updated before -// |asn| is serialized. +// `algor1` and `algor2` may point into part of `asn` and will be updated before +// `asn` is serialized. // -// WARNING: |data| must be a pointer with the same type as |it|'s corresponding +// WARNING: `data` must be a pointer with the same type as `it`'s corresponding // C type. Using the wrong type is a potentially exploitable memory error. OPENSSL_EXPORT int ASN1_item_sign_ctx(const ASN1_ITEM *it, X509_ALGOR *algor1, X509_ALGOR *algor2, @@ -4525,55 +4525,55 @@ // The following functions expose portions of certificate validation. They are // exported for compatibility with existing callers, or to support some obscure // use cases. Most callers, however, will not need these functions and should -// instead use |X509_STORE_CTX| APIs. +// instead use `X509_STORE_CTX` APIs. -// X509_supported_extension returns one if |ex| is a critical X.509 certificate -// extension, supported by |X509_verify_cert|, and zero otherwise. +// X509_supported_extension returns one if `ex` is a critical X.509 certificate +// extension, supported by `X509_verify_cert`, and zero otherwise. // // Note this function only reports certificate extensions (as opposed to CRL or // CRL extensions), and only extensions that are expected to be marked critical. -// Additionally, |X509_verify_cert| checks for unsupported critical extensions +// Additionally, `X509_verify_cert` checks for unsupported critical extensions // internally, so most callers will not need to call this function separately. OPENSSL_EXPORT int X509_supported_extension(const X509_EXTENSION *ex); -// X509_check_ca returns one if |x509| may be considered a CA certificate, +// X509_check_ca returns one if `x509` may be considered a CA certificate, // according to basic constraints and key usage extensions. Otherwise, it -// returns zero. If |x509| is an X509v1 certificate, and thus has no extensions, +// returns zero. If `x509` is an X509v1 certificate, and thus has no extensions, // it is considered eligible. // -// This function returning one does not indicate that |x509| is trusted, only +// This function returning one does not indicate that `x509` is trusted, only // that it is eligible to be a CA. OPENSSL_EXPORT int X509_check_ca(const X509 *x509); -// X509_check_issued checks if |issuer| and |subject|'s name, authority key -// identifier, and key usage fields allow |issuer| to have issued |subject|. It -// returns |X509_V_OK| on success and an |X509_V_ERR_*| value otherwise. +// X509_check_issued checks if `issuer` and `subject`'s name, authority key +// identifier, and key usage fields allow `issuer` to have issued `subject`. It +// returns `X509_V_OK` on success and an `X509_V_ERR_*` value otherwise. // -// This function does not check the signature on |subject|. Rather, it is +// This function does not check the signature on `subject`. Rather, it is // intended to prune the set of possible issuer certificates during // path-building. OPENSSL_EXPORT int X509_check_issued(const X509 *issuer, const X509 *subject); -// NAME_CONSTRAINTS_check checks if |x509| satisfies name constraints in |nc|. -// It returns |X509_V_OK| on success and some |X509_V_ERR_*| constant on error. +// NAME_CONSTRAINTS_check checks if `x509` satisfies name constraints in `nc`. +// It returns `X509_V_OK` on success and some `X509_V_ERR_*` constant on error. OPENSSL_EXPORT int NAME_CONSTRAINTS_check(const X509 *x509, const NAME_CONSTRAINTS *nc); -// X509_check_host checks if |x509| matches the DNS name |chk|. It returns one -// on match, zero on mismatch, or a negative number on error. |flags| should be -// some combination of |X509_CHECK_FLAG_*| and modifies the behavior. On match, -// if |out_peername| is non-NULL, it additionally sets |*out_peername| to a +// X509_check_host checks if `x509` matches the DNS name `chk`. It returns one +// on match, zero on mismatch, or a negative number on error. `flags` should be +// some combination of `X509_CHECK_FLAG_*` and modifies the behavior. On match, +// if `out_peername` is non-NULL, it additionally sets `*out_peername` to a // newly-allocated, NUL-terminated string containing the DNS name or wildcard in -// the certificate which matched. The caller must then free |*out_peername| with -// |OPENSSL_free| when done. +// the certificate which matched. The caller must then free `*out_peername` with +// `OPENSSL_free` when done. // // By default, both subject alternative names and the subject's common name // attribute are checked. The latter has long been deprecated, so callers should -// include |X509_CHECK_FLAG_NEVER_CHECK_SUBJECT| in |flags| to use the standard +// include `X509_CHECK_FLAG_NEVER_CHECK_SUBJECT` in `flags` to use the standard // behavior. https://crbug.com/boringssl/464 tracks fixing the default. // -// This function does not check if |x509| is a trusted certificate, only if, -// were it trusted, it would match |chk|. +// This function does not check if `x509` is a trusted certificate, only if, +// were it trusted, it would match `chk`. // // WARNING: This function differs from the usual calling convention and may // return either 0 or a negative number on error. @@ -4583,16 +4583,16 @@ size_t chklen, unsigned int flags, char **out_peername); -// X509_check_email checks if |x509| matches the email address |chk|. It returns -// one on match, zero on mismatch, or a negative number on error. |flags| should -// be some combination of |X509_CHECK_FLAG_*| and modifies the behavior. +// X509_check_email checks if `x509` matches the email address `chk`. It returns +// one on match, zero on mismatch, or a negative number on error. `flags` should +// be some combination of `X509_CHECK_FLAG_*` and modifies the behavior. // // By default, both subject alternative names and the subject's email address -// attribute are checked. The |X509_CHECK_FLAG_NEVER_CHECK_SUBJECT| flag may be +// attribute are checked. The `X509_CHECK_FLAG_NEVER_CHECK_SUBJECT` flag may be // used to change this behavior. // -// This function does not check if |x509| is a trusted certificate, only if, -// were it trusted, it would match |chk|. +// This function does not check if `x509` is a trusted certificate, only if, +// were it trusted, it would match `chk`. // // WARNING: This function differs from the usual calling convention and may // return either 0 or a negative number on error. @@ -4601,14 +4601,14 @@ OPENSSL_EXPORT int X509_check_email(const X509 *x509, const char *chk, size_t chklen, unsigned int flags); -// X509_check_ip checks if |x509| matches the IP address |chk|. The IP address +// X509_check_ip checks if `x509` matches the IP address `chk`. The IP address // is represented in byte form and should be 4 bytes for an IPv4 address and 16 // bytes for an IPv6 address. It returns one on match, zero on mismatch, or a -// negative number on error. |flags| should be some combination of -// |X509_CHECK_FLAG_*| and modifies the behavior. +// negative number on error. `flags` should be some combination of +// `X509_CHECK_FLAG_*` and modifies the behavior. // -// This function does not check if |x509| is a trusted certificate, only if, -// were it trusted, it would match |chk|. +// This function does not check if `x509` is a trusted certificate, only if, +// were it trusted, it would match `chk`. // // WARNING: This function differs from the usual calling convention and may // return either 0 or a negative number on error. @@ -4617,8 +4617,8 @@ OPENSSL_EXPORT int X509_check_ip(const X509 *x509, const uint8_t *chk, size_t chklen, unsigned int flags); -// X509_check_ip_asc behaves like |X509_check_ip| except the IP address is -// specified in textual form in |ipasc|. +// X509_check_ip_asc behaves like `X509_check_ip` except the IP address is +// specified in textual form in `ipasc`. // // WARNING: This function differs from the usual calling convention and may // return either 0 or a negative number on error. @@ -4627,70 +4627,70 @@ OPENSSL_EXPORT int X509_check_ip_asc(const X509 *x509, const char *ipasc, unsigned int flags); -// X509_STORE_CTX_get1_issuer looks up a candidate trusted issuer for |x509| out -// of |ctx|'s |X509_STORE|, based on the criteria in |X509_check_issued|. If one -// was found, it returns one and sets |*out_issuer| to the issuer. The caller -// must release |*out_issuer| with |X509_free| when done. If none was found, it -// returns zero and leaves |*out_issuer| unchanged. +// X509_STORE_CTX_get1_issuer looks up a candidate trusted issuer for `x509` out +// of `ctx`'s `X509_STORE`, based on the criteria in `X509_check_issued`. If one +// was found, it returns one and sets `*out_issuer` to the issuer. The caller +// must release `*out_issuer` with `X509_free` when done. If none was found, it +// returns zero and leaves `*out_issuer` unchanged. // // This function only searches for trusted issuers. It does not consider -// untrusted intermediates passed in to |X509_STORE_CTX_init|. +// untrusted intermediates passed in to `X509_STORE_CTX_init`. OPENSSL_EXPORT int X509_STORE_CTX_get1_issuer(X509 **out_issuer, X509_STORE_CTX *ctx, const X509 *x509); -// X509_check_purpose performs checks if |x509|'s basic constraints, key usage, -// and extended key usage extensions for the specified purpose. |purpose| should -// be one of |X509_PURPOSE_*| constants. See |X509_VERIFY_PARAM_set_purpose| for -// details. It returns one if |x509|'s extensions are consistent with |purpose| -// and zero otherwise. If |ca| is non-zero, |x509| is checked as a CA +// X509_check_purpose performs checks if `x509`'s basic constraints, key usage, +// and extended key usage extensions for the specified purpose. `purpose` should +// be one of `X509_PURPOSE_*` constants. See `X509_VERIFY_PARAM_set_purpose` for +// details. It returns one if `x509`'s extensions are consistent with `purpose` +// and zero otherwise. If `ca` is non-zero, `x509` is checked as a CA // certificate. Otherwise, it is checked as an end-entity certificate. // -// If |purpose| is -1, this function performs no purpose checks, but it parses -// some extensions in |x509| and may return zero on syntax error. Historically, +// If `purpose` is -1, this function performs no purpose checks, but it parses +// some extensions in `x509` and may return zero on syntax error. Historically, // callers primarily used this function to trigger this parsing, but this is no -// longer necessary. Functions acting on |X509| will internally parse as needed. +// longer necessary. Functions acting on `X509` will internally parse as needed. OPENSSL_EXPORT int X509_check_purpose(X509 *x509, int purpose, int ca); #define X509_TRUST_TRUSTED 1 #define X509_TRUST_REJECTED 2 #define X509_TRUST_UNTRUSTED 3 -// X509_check_trust checks if |x509| is a valid trust anchor for trust type -// |id|. See |X509_VERIFY_PARAM_set_trust| for details. It returns -// |X509_TRUST_TRUSTED| if |x509| is a trust anchor, |X509_TRUST_REJECTED| if it -// was distrusted, and |X509_TRUST_UNTRUSTED| otherwise. |id| should be one of -// the |X509_TRUST_*| constants, or zero to indicate the default behavior. -// |flags| should be zero and is ignored. +// X509_check_trust checks if `x509` is a valid trust anchor for trust type +// `id`. See `X509_VERIFY_PARAM_set_trust` for details. It returns +// `X509_TRUST_TRUSTED` if `x509` is a trust anchor, `X509_TRUST_REJECTED` if it +// was distrusted, and `X509_TRUST_UNTRUSTED` otherwise. `id` should be one of +// the `X509_TRUST_*` constants, or zero to indicate the default behavior. +// `flags` should be zero and is ignored. OPENSSL_EXPORT int X509_check_trust(X509 *x509, int id, int flags); // X509_STORE_CTX_get1_certs returns a newly-allocated stack containing all -// trusted certificates in |ctx|'s |X509_STORE| whose subject matches |name|, or -// NULL on error. The caller must release the result with |sk_X509_pop_free| and -// |X509_free| when done. +// trusted certificates in `ctx`'s `X509_STORE` whose subject matches `name`, or +// NULL on error. The caller must release the result with `sk_X509_pop_free` and +// `X509_free` when done. OPENSSL_EXPORT STACK_OF(X509) *X509_STORE_CTX_get1_certs(X509_STORE_CTX *ctx, const X509_NAME *name); // X509_STORE_CTX_get1_crls returns a newly-allocated stack containing all -// CRLs in |ctx|'s |X509_STORE| whose subject matches |name|, or NULL on error. -// The caller must release the result with |sk_X509_CRL_pop_free| and -// |X509_CRL_free| when done. +// CRLs in `ctx`'s `X509_STORE` whose subject matches `name`, or NULL on error. +// The caller must release the result with `sk_X509_CRL_pop_free` and +// `X509_CRL_free` when done. OPENSSL_EXPORT STACK_OF(X509_CRL) *X509_STORE_CTX_get1_crls( X509_STORE_CTX *ctx, const X509_NAME *name); -// X509_STORE_CTX_get_by_subject looks up an object of type |type| in |ctx|'s -// |X509_STORE| that matches |name|. |type| should be one of the |X509_LU_*| +// X509_STORE_CTX_get_by_subject looks up an object of type `type` in `ctx`'s +// `X509_STORE` that matches `name`. `type` should be one of the `X509_LU_*` // constants to indicate the type of object. If a match was found, it stores the -// result in |ret| and returns one. Otherwise, it returns zero. If multiple +// result in `ret` and returns one. Otherwise, it returns zero. If multiple // objects match, this function outputs an arbitrary one. // -// WARNING: |ret| must be in the empty state, as returned by |X509_OBJECT_new|. -// Otherwise, the object currently in |ret| will be leaked when overwritten. +// WARNING: `ret` must be in the empty state, as returned by `X509_OBJECT_new`. +// Otherwise, the object currently in `ret` will be leaked when overwritten. // https://crbug.com/boringssl/685 tracks fixing this. // // WARNING: Multiple trusted certificates or CRLs may share a name. In this // case, this function returns an arbitrary match. Use -// |X509_STORE_CTX_get1_certs| or |X509_STORE_CTX_get1_crls| instead. +// `X509_STORE_CTX_get1_certs` or `X509_STORE_CTX_get1_crls` instead. OPENSSL_EXPORT int X509_STORE_CTX_get_by_subject(X509_STORE_CTX *ctx, int type, const X509_NAME *name, X509_OBJECT *ret); @@ -4698,7 +4698,7 @@ // X.509 information. // -// |X509_INFO| is the return type for |PEM_X509_INFO_read_bio|, defined in +// `X509_INFO` is the return type for `PEM_X509_INFO_read_bio`, defined in // <openssl/pem.h>. It is used to store a certificate, CRL, or private key. This // type is defined in this header for OpenSSL compatibility. @@ -4718,25 +4718,25 @@ DEFINE_STACK_OF(X509_INFO) -// X509_INFO_free releases memory associated with |info|. +// X509_INFO_free releases memory associated with `info`. OPENSSL_EXPORT void X509_INFO_free(X509_INFO *info); // Deprecated custom extension registration. // // The following functions allow callers to register custom extensions for use -// with |X509V3_EXT_d2i| and related functions. This mechanism is deprecated and -// will be removed in the future. As discussed in |X509V3_EXT_add|, it is not +// with `X509V3_EXT_d2i` and related functions. This mechanism is deprecated and +// will be removed in the future. As discussed in `X509V3_EXT_add`, it is not // possible to safely register a custom extension without risking race // conditions and memory errors when linked with other users of BoringSSL. // // Moreover, it is not necessary to register a custom extension to process // extensions unknown to BoringSSL. Registration does not impact certificate // verification. Caller should instead use functions such as -// |ASN1_OBJECT_create|, |X509_get_ext_by_OBJ|, |X509_EXTENSION_get_data|, and -// |X509_EXTENSION_create_by_OBJ| to inspect or create extensions directly. +// `ASN1_OBJECT_create`, `X509_get_ext_by_OBJ`, `X509_EXTENSION_get_data`, and +// `X509_EXTENSION_create_by_OBJ` to inspect or create extensions directly. -// The following function pointer types are used in |X509V3_EXT_METHOD|. +// The following function pointer types are used in `X509V3_EXT_METHOD`. typedef void *(*X509V3_EXT_NEW)(void); typedef void (*X509V3_EXT_FREE)(void *ext); typedef void *(*X509V3_EXT_D2I)(void *ext, const uint8_t **inp, long len); @@ -4755,20 +4755,20 @@ typedef void *(*X509V3_EXT_R2I)(const X509V3_EXT_METHOD *method, const X509V3_CTX *ctx, const char *str); -// A v3_ext_method, aka |X509V3_EXT_METHOD|, is a deprecated type which defines +// A v3_ext_method, aka `X509V3_EXT_METHOD`, is a deprecated type which defines // a custom extension. struct v3_ext_method { // ext_nid is the NID of the extension. int ext_nid; - // ext_flags is a combination of |X509V3_EXT_*| constants. + // ext_flags is a combination of `X509V3_EXT_*` constants. int ext_flags; // it determines how values of this extension are allocated, released, parsed, // and marshalled. This must be non-NULL. ASN1_ITEM_EXP *it; - // The following functions are ignored in favor of |it|. They are retained in + // The following functions are ignored in favor of `it`. They are retained in // the struct only for source compatibility with existing struct definitions. X509V3_EXT_NEW ext_new; X509V3_EXT_FREE ext_free; @@ -4791,31 +4791,31 @@ void *usr_data; // Any extension specific data } /* X509V3_EXT_METHOD */; -// X509V3_EXT_MULTILINE causes the result of an |X509V3_EXT_METHOD|'s |i2v| +// X509V3_EXT_MULTILINE causes the result of an `X509V3_EXT_METHOD`'s `i2v` // function to be printed on separate lines, rather than separated by commas. #define X509V3_EXT_MULTILINE 0x4 -// X509V3_EXT_get returns the |X509V3_EXT_METHOD| corresponding to |ext|'s +// X509V3_EXT_get returns the `X509V3_EXT_METHOD` corresponding to `ext`'s // extension type, or NULL if none was registered. OPENSSL_EXPORT const X509V3_EXT_METHOD *X509V3_EXT_get( const X509_EXTENSION *ext); -// X509V3_EXT_get_nid returns the |X509V3_EXT_METHOD| corresponding to |nid|, or +// X509V3_EXT_get_nid returns the `X509V3_EXT_METHOD` corresponding to `nid`, or // NULL if none was registered. OPENSSL_EXPORT const X509V3_EXT_METHOD *X509V3_EXT_get_nid(int nid); -// X509V3_EXT_add registers |ext| as a custom extension for the extension type -// |ext->ext_nid|. |ext| must be valid for the remainder of the address space's +// X509V3_EXT_add registers `ext` as a custom extension for the extension type +// `ext->ext_nid`. `ext` must be valid for the remainder of the address space's // lifetime. It returns one on success and zero on error. // // WARNING: This function modifies global state. If other code in the same -// address space also registers an extension with type |ext->ext_nid|, the two +// address space also registers an extension with type `ext->ext_nid`, the two // registrations will conflict. Which registration takes effect is undefined. If // the two registrations use incompatible in-memory representations, code // expecting the other registration will then cast a type to the wrong type, // resulting in a potentially exploitable memory error. This conflict can also -// occur if BoringSSL later adds support for |ext->ext_nid|, with a different -// in-memory representation than the one expected by |ext|. +// occur if BoringSSL later adds support for `ext->ext_nid`, with a different +// in-memory representation than the one expected by `ext`. // // This function, additionally, is not thread-safe and cannot be called // concurrently with any other BoringSSL function. @@ -4823,15 +4823,15 @@ // As a result, it is impossible to safely use this function. Registering a // custom extension has no impact on certificate verification so, instead, // callers should simply handle the custom extension with the byte-based -// |X509_EXTENSION| APIs directly. Registering |ext| with the library has little +// `X509_EXTENSION` APIs directly. Registering `ext` with the library has little // practical value. OPENSSL_EXPORT OPENSSL_DEPRECATED int X509V3_EXT_add(X509V3_EXT_METHOD *ext); -// X509V3_EXT_add_alias registers a custom extension with NID |nid_to|. The -// corresponding ASN.1 type is copied from |nid_from|. It returns one on success +// X509V3_EXT_add_alias registers a custom extension with NID `nid_to`. The +// corresponding ASN.1 type is copied from `nid_from`. It returns one on success // and zero on error. // -// WARNING: Do not use this function. See |X509V3_EXT_add|. +// WARNING: Do not use this function. See `X509V3_EXT_add`. OPENSSL_EXPORT OPENSSL_DEPRECATED int X509V3_EXT_add_alias(int nid_to, int nid_from); @@ -4855,10 +4855,10 @@ // review than most of the library and may have bugs including memory leaks or // crashes. -// v3_ext_ctx, aka |X509V3_CTX|, contains additional context information for +// v3_ext_ctx, aka `X509V3_CTX`, contains additional context information for // constructing extensions. Some string formats reference additional values in -// these objects. It must be initialized with |X509V3_set_ctx| or -// |X509V3_set_ctx_test| before use. +// these objects. It must be initialized with `X509V3_set_ctx` or +// `X509V3_set_ctx_test` before use. struct v3_ext_ctx { int flags; const X509 *issuer_cert; @@ -4870,17 +4870,17 @@ #define X509V3_CTX_TEST 0x1 -// X509V3_set_ctx initializes |ctx| with the specified objects. Some string +// X509V3_set_ctx initializes `ctx` with the specified objects. Some string // formats will reference fields in these objects. Each object may be NULL to -// omit it, in which case those formats cannot be used. |flags| should be zero, -// unless called via |X509V3_set_ctx_test|. +// omit it, in which case those formats cannot be used. `flags` should be zero, +// unless called via `X509V3_set_ctx_test`. // -// |issuer|, |subject|, |req|, and |crl|, if non-NULL, must outlive |ctx|. +// `issuer`, `subject`, `req`, and `crl`, if non-NULL, must outlive `ctx`. OPENSSL_EXPORT void X509V3_set_ctx(X509V3_CTX *ctx, const X509 *issuer, const X509 *subject, const X509_REQ *req, const X509_CRL *crl, int flags); -// X509V3_set_ctx_test calls |X509V3_set_ctx| without any reference objects and +// X509V3_set_ctx_test calls `X509V3_set_ctx` without any reference objects and // mocks out some features that use them. The resulting extensions may be // incomplete and should be discarded. This can be used to partially validate // syntax. @@ -4889,145 +4889,145 @@ #define X509V3_set_ctx_test(ctx) \ X509V3_set_ctx(ctx, NULL, NULL, NULL, NULL, X509V3_CTX_TEST) -// X509V3_set_nconf sets |ctx| to use |conf| as the config database. |ctx| must -// have previously been initialized by |X509V3_set_ctx| or -// |X509V3_set_ctx_test|. Some string formats will reference sections in |conf|. -// |conf| may be NULL, in which case these formats cannot be used. If non-NULL, -// |conf| must outlive |ctx|. +// X509V3_set_nconf sets `ctx` to use `conf` as the config database. `ctx` must +// have previously been initialized by `X509V3_set_ctx` or +// `X509V3_set_ctx_test`. Some string formats will reference sections in `conf`. +// `conf` may be NULL, in which case these formats cannot be used. If non-NULL, +// `conf` must outlive `ctx`. OPENSSL_EXPORT void X509V3_set_nconf(X509V3_CTX *ctx, const CONF *conf); -// X509V3_set_ctx_nodb calls |X509V3_set_nconf| with no config database. +// X509V3_set_ctx_nodb calls `X509V3_set_nconf` with no config database. #define X509V3_set_ctx_nodb(ctx) X509V3_set_nconf(ctx, NULL) -// X509V3_EXT_nconf constructs an extension of type specified by |name|, and -// value specified by |value|. It returns a newly-allocated |X509_EXTENSION| -// object on success, or NULL on error. |conf| and |ctx| specify additional -// information referenced by some formats. Either |conf| or |ctx| may be NULL, +// X509V3_EXT_nconf constructs an extension of type specified by `name`, and +// value specified by `value`. It returns a newly-allocated `X509_EXTENSION` +// object on success, or NULL on error. `conf` and `ctx` specify additional +// information referenced by some formats. Either `conf` or `ctx` may be NULL, // in which case features which use it will be disabled. // -// If non-NULL, |ctx| must be initialized with |X509V3_set_ctx| or -// |X509V3_set_ctx_test|. +// If non-NULL, `ctx` must be initialized with `X509V3_set_ctx` or +// `X509V3_set_ctx_test`. // -// Both |conf| and |ctx| provide a |CONF| object. When |ctx| is non-NULL, most -// features use the |ctx| copy, configured with |X509V3_set_ctx|, but some use -// |conf|. Callers should ensure the two match to avoid surprisingly behavior. +// Both `conf` and `ctx` provide a `CONF` object. When `ctx` is non-NULL, most +// features use the `ctx` copy, configured with `X509V3_set_ctx`, but some use +// `conf`. Callers should ensure the two match to avoid surprisingly behavior. OPENSSL_EXPORT X509_EXTENSION *X509V3_EXT_nconf(const CONF *conf, const X509V3_CTX *ctx, const char *name, const char *value); -// X509V3_EXT_nconf_nid behaves like |X509V3_EXT_nconf|, except the extension +// X509V3_EXT_nconf_nid behaves like `X509V3_EXT_nconf`, except the extension // type is specified as a NID. OPENSSL_EXPORT X509_EXTENSION *X509V3_EXT_nconf_nid(const CONF *conf, const X509V3_CTX *ctx, int ext_nid, const char *value); -// X509V3_EXT_conf_nid calls |X509V3_EXT_nconf_nid|. |conf| must be NULL. +// X509V3_EXT_conf_nid calls `X509V3_EXT_nconf_nid`. `conf` must be NULL. OPENSSL_EXPORT X509_EXTENSION *X509V3_EXT_conf_nid(CRYPTO_MUST_BE_NULL *conf, const X509V3_CTX *ctx, int ext_nid, const char *value); -// X509V3_EXT_add_nconf_sk looks up the section named |section| in |conf|. For -// each |CONF_VALUE| in the section, it constructs an extension as in -// |X509V3_EXT_nconf|, taking |name| and |value| from the |CONF_VALUE|. Each new -// extension is appended to |*sk|. If |*sk| is non-NULL, and at least one -// extension is added, it sets |*sk| to a newly-allocated -// |STACK_OF(X509_EXTENSION)|. It returns one on success and zero on error. +// X509V3_EXT_add_nconf_sk looks up the section named `section` in `conf`. For +// each `CONF_VALUE` in the section, it constructs an extension as in +// `X509V3_EXT_nconf`, taking `name` and `value` from the `CONF_VALUE`. Each new +// extension is appended to `*sk`. If `*sk` is non-NULL, and at least one +// extension is added, it sets `*sk` to a newly-allocated +// `STACK_OF(X509_EXTENSION)`. It returns one on success and zero on error. OPENSSL_EXPORT int X509V3_EXT_add_nconf_sk(const CONF *conf, const X509V3_CTX *ctx, const char *section, STACK_OF(X509_EXTENSION) **sk); -// X509V3_EXT_add_nconf adds extensions to |cert| as in -// |X509V3_EXT_add_nconf_sk|. It returns one on success and zero on error. +// X509V3_EXT_add_nconf adds extensions to `cert` as in +// `X509V3_EXT_add_nconf_sk`. It returns one on success and zero on error. OPENSSL_EXPORT int X509V3_EXT_add_nconf(const CONF *conf, const X509V3_CTX *ctx, const char *section, X509 *cert); -// X509V3_EXT_REQ_add_nconf adds extensions to |req| as in -// |X509V3_EXT_add_nconf_sk|. It returns one on success and zero on error. +// X509V3_EXT_REQ_add_nconf adds extensions to `req` as in +// `X509V3_EXT_add_nconf_sk`. It returns one on success and zero on error. OPENSSL_EXPORT int X509V3_EXT_REQ_add_nconf(const CONF *conf, const X509V3_CTX *ctx, const char *section, X509_REQ *req); -// X509V3_EXT_CRL_add_nconf adds extensions to |crl| as in -// |X509V3_EXT_add_nconf_sk|. It returns one on success and zero on error. +// X509V3_EXT_CRL_add_nconf adds extensions to `crl` as in +// `X509V3_EXT_add_nconf_sk`. It returns one on success and zero on error. OPENSSL_EXPORT int X509V3_EXT_CRL_add_nconf(const CONF *conf, const X509V3_CTX *ctx, const char *section, X509_CRL *crl); -// i2s_ASN1_OCTET_STRING returns a human-readable representation of |oct| as a -// newly-allocated, NUL-terminated string, or NULL on error. |method| is -// ignored. The caller must release the result with |OPENSSL_free| when done. +// i2s_ASN1_OCTET_STRING returns a human-readable representation of `oct` as a +// newly-allocated, NUL-terminated string, or NULL on error. `method` is +// ignored. The caller must release the result with `OPENSSL_free` when done. OPENSSL_EXPORT char *i2s_ASN1_OCTET_STRING(const X509V3_EXT_METHOD *method, const ASN1_OCTET_STRING *oct); -// s2i_ASN1_OCTET_STRING decodes |str| as a hexadecimal byte string, with +// s2i_ASN1_OCTET_STRING decodes `str` as a hexadecimal byte string, with // optional colon separators between bytes. It returns a newly-allocated -// |ASN1_OCTET_STRING| with the result on success, or NULL on error. |method| -// and |ctx| are ignored. +// `ASN1_OCTET_STRING` with the result on success, or NULL on error. `method` +// and `ctx` are ignored. OPENSSL_EXPORT ASN1_OCTET_STRING *s2i_ASN1_OCTET_STRING( const X509V3_EXT_METHOD *method, const X509V3_CTX *ctx, const char *str); -// i2s_ASN1_INTEGER returns a human-readable representation of |aint| as a -// newly-allocated, NUL-terminated string, or NULL on error. |method| is -// ignored. The caller must release the result with |OPENSSL_free| when done. +// i2s_ASN1_INTEGER returns a human-readable representation of `aint` as a +// newly-allocated, NUL-terminated string, or NULL on error. `method` is +// ignored. The caller must release the result with `OPENSSL_free` when done. OPENSSL_EXPORT char *i2s_ASN1_INTEGER(const X509V3_EXT_METHOD *method, const ASN1_INTEGER *aint); -// s2i_ASN1_INTEGER decodes |value| as the ASCII representation of an integer, -// and returns a newly-allocated |ASN1_INTEGER| containing the result, or NULL -// on error. |method| is ignored. If |value| begins with "0x" or "0X", the input +// s2i_ASN1_INTEGER decodes `value` as the ASCII representation of an integer, +// and returns a newly-allocated `ASN1_INTEGER` containing the result, or NULL +// on error. `method` is ignored. If `value` begins with "0x" or "0X", the input // is decoded in hexadecimal, otherwise decimal. OPENSSL_EXPORT ASN1_INTEGER *s2i_ASN1_INTEGER(const X509V3_EXT_METHOD *method, const char *value); -// i2s_ASN1_ENUMERATED returns a human-readable representation of |aint| as a -// newly-allocated, NUL-terminated string, or NULL on error. |method| is -// ignored. The caller must release the result with |OPENSSL_free| when done. +// i2s_ASN1_ENUMERATED returns a human-readable representation of `aint` as a +// newly-allocated, NUL-terminated string, or NULL on error. `method` is +// ignored. The caller must release the result with `OPENSSL_free` when done. OPENSSL_EXPORT char *i2s_ASN1_ENUMERATED(const X509V3_EXT_METHOD *method, const ASN1_ENUMERATED *aint); -// X509V3_conf_free releases memory associated with |CONF_VALUE|. +// X509V3_conf_free releases memory associated with `CONF_VALUE`. OPENSSL_EXPORT void X509V3_conf_free(CONF_VALUE *val); -// i2v_GENERAL_NAME serializes |gen| as a |CONF_VALUE|. If |ret| is non-NULL, it -// appends the value to |ret| and returns |ret| on success or NULL on error. If -// it returns NULL, the caller is still responsible for freeing |ret|. If |ret| -// is NULL, it returns a newly-allocated |STACK_OF(CONF_VALUE)| containing the -// result. |method| is ignored. When done, the caller should release the result -// with |sk_CONF_VALUE_pop_free| and |X509V3_conf_free|. +// i2v_GENERAL_NAME serializes `gen` as a `CONF_VALUE`. If `ret` is non-NULL, it +// appends the value to `ret` and returns `ret` on success or NULL on error. If +// it returns NULL, the caller is still responsible for freeing `ret`. If `ret` +// is NULL, it returns a newly-allocated `STACK_OF(CONF_VALUE)` containing the +// result. `method` is ignored. When done, the caller should release the result +// with `sk_CONF_VALUE_pop_free` and `X509V3_conf_free`. // // Do not use this function. This is an internal implementation detail of the // human-readable print functions. If extracting a SAN list from a certificate, -// look at |gen| directly. +// look at `gen` directly. OPENSSL_EXPORT STACK_OF(CONF_VALUE) *i2v_GENERAL_NAME( const X509V3_EXT_METHOD *method, const GENERAL_NAME *gen, STACK_OF(CONF_VALUE) *ret); -// i2v_GENERAL_NAMES serializes |gen| as a list of |CONF_VALUE|s. If |ret| is -// non-NULL, it appends the values to |ret| and returns |ret| on success or NULL +// i2v_GENERAL_NAMES serializes `gen` as a list of `CONF_VALUE`s. If `ret` is +// non-NULL, it appends the values to `ret` and returns `ret` on success or NULL // on error. If it returns NULL, the caller is still responsible for freeing -// |ret|. If |ret| is NULL, it returns a newly-allocated |STACK_OF(CONF_VALUE)| -// containing the results. |method| is ignored. +// `ret`. If `ret` is NULL, it returns a newly-allocated `STACK_OF(CONF_VALUE)` +// containing the results. `method` is ignored. // // Do not use this function. This is an internal implementation detail of the // human-readable print functions. If extracting a SAN list from a certificate, -// look at |gen| directly. +// look at `gen` directly. OPENSSL_EXPORT STACK_OF(CONF_VALUE) *i2v_GENERAL_NAMES( const X509V3_EXT_METHOD *method, const GENERAL_NAMES *gen, STACK_OF(CONF_VALUE) *extlist); -// a2i_IPADDRESS decodes |ipasc| as the textual representation of an IPv4 or -// IPv6 address. On success, it returns a newly-allocated |ASN1_OCTET_STRING| +// a2i_IPADDRESS decodes `ipasc` as the textual representation of an IPv4 or +// IPv6 address. On success, it returns a newly-allocated `ASN1_OCTET_STRING` // containing the decoded IP address. IPv4 addresses are represented as 4-byte // strings and IPv6 addresses as 16-byte strings. On failure, it returns NULL. OPENSSL_EXPORT ASN1_OCTET_STRING *a2i_IPADDRESS(const char *ipasc); -// a2i_IPADDRESS_NC decodes |ipasc| as the textual representation of an IPv4 or +// a2i_IPADDRESS_NC decodes `ipasc` as the textual representation of an IPv4 or // IPv6 address range. On success, it returns a newly-allocated -// |ASN1_OCTET_STRING| containing the decoded IP address, followed by the +// `ASN1_OCTET_STRING` containing the decoded IP address, followed by the // decoded mask. IPv4 ranges are represented as 8-byte strings and IPv6 ranges // as 32-byte strings. On failure, it returns NULL. // @@ -5039,76 +5039,76 @@ // Deprecated functions. -// X509_get_notBefore returns |x509|'s notBefore time. Note this function is not -// const-correct for legacy reasons. Use |X509_get0_notBefore| or -// |X509_getm_notBefore| instead. +// X509_get_notBefore returns `x509`'s notBefore time. Note this function is not +// const-correct for legacy reasons. Use `X509_get0_notBefore` or +// `X509_getm_notBefore` instead. OPENSSL_EXPORT ASN1_TIME *X509_get_notBefore(const X509 *x509); -// X509_get_notAfter returns |x509|'s notAfter time. Note this function is not -// const-correct for legacy reasons. Use |X509_get0_notAfter| or -// |X509_getm_notAfter| instead. +// X509_get_notAfter returns `x509`'s notAfter time. Note this function is not +// const-correct for legacy reasons. Use `X509_get0_notAfter` or +// `X509_getm_notAfter` instead. OPENSSL_EXPORT ASN1_TIME *X509_get_notAfter(const X509 *x509); -// X509_set_notBefore calls |X509_set1_notBefore|. Use |X509_set1_notBefore| +// X509_set_notBefore calls `X509_set1_notBefore`. Use `X509_set1_notBefore` // instead. OPENSSL_EXPORT int X509_set_notBefore(X509 *x509, const ASN1_TIME *tm); -// X509_set_notAfter calls |X509_set1_notAfter|. Use |X509_set1_notAfter| +// X509_set_notAfter calls `X509_set1_notAfter`. Use `X509_set1_notAfter` // instead. OPENSSL_EXPORT int X509_set_notAfter(X509 *x509, const ASN1_TIME *tm); -// X509_CRL_get_lastUpdate returns a mutable pointer to |crl|'s thisUpdate time. +// X509_CRL_get_lastUpdate returns a mutable pointer to `crl`'s thisUpdate time. // The OpenSSL API refers to this field as lastUpdate. // -// Use |X509_CRL_get0_lastUpdate| or |X509_CRL_set1_lastUpdate| instead. +// Use `X509_CRL_get0_lastUpdate` or `X509_CRL_set1_lastUpdate` instead. OPENSSL_EXPORT ASN1_TIME *X509_CRL_get_lastUpdate(X509_CRL *crl); -// X509_CRL_get_nextUpdate returns a mutable pointer to |crl|'s nextUpdate time, -// or NULL if |crl| has none. Use |X509_CRL_get0_nextUpdate| or -// |X509_CRL_set1_nextUpdate| instead. +// X509_CRL_get_nextUpdate returns a mutable pointer to `crl`'s nextUpdate time, +// or NULL if `crl` has none. Use `X509_CRL_get0_nextUpdate` or +// `X509_CRL_set1_nextUpdate` instead. OPENSSL_EXPORT ASN1_TIME *X509_CRL_get_nextUpdate(X509_CRL *crl); -// X509_extract_key is a legacy alias to |X509_get_pubkey|. Use -// |X509_get_pubkey| instead. +// X509_extract_key is a legacy alias to `X509_get_pubkey`. Use +// `X509_get_pubkey` instead. #define X509_extract_key(x) X509_get_pubkey(x) -// X509_REQ_extract_key is a legacy alias for |X509_REQ_get_pubkey|. +// X509_REQ_extract_key is a legacy alias for `X509_REQ_get_pubkey`. #define X509_REQ_extract_key(a) X509_REQ_get_pubkey(a) -// X509_name_cmp is a legacy alias for |X509_NAME_cmp|. +// X509_name_cmp is a legacy alias for `X509_NAME_cmp`. #define X509_name_cmp(a, b) X509_NAME_cmp((a), (b)) -// The following symbols are deprecated aliases to |X509_CRL_set1_*|. +// The following symbols are deprecated aliases to `X509_CRL_set1_*`. #define X509_CRL_set_lastUpdate X509_CRL_set1_lastUpdate #define X509_CRL_set_nextUpdate X509_CRL_set1_nextUpdate -// X509_get_serialNumber returns a mutable pointer to |x509|'s serial number. -// Prefer |X509_get0_serialNumber|. +// X509_get_serialNumber returns a mutable pointer to `x509`'s serial number. +// Prefer `X509_get0_serialNumber`. OPENSSL_EXPORT ASN1_INTEGER *X509_get_serialNumber(X509 *x509); -// X509_NAME_get_text_by_OBJ finds the first attribute with type |obj| in -// |name|. If found, it writes the value's UTF-8 representation to |buf|. +// X509_NAME_get_text_by_OBJ finds the first attribute with type `obj` in +// `name`. If found, it writes the value's UTF-8 representation to `buf`. // followed by a NUL byte, and returns the number of bytes in the output, // excluding the NUL byte. This is unlike OpenSSL which returns the raw -// ASN1_STRING data. The UTF-8 encoding of the |ASN1_STRING| may not contain a 0 +// ASN1_STRING data. The UTF-8 encoding of the `ASN1_STRING` may not contain a 0 // codepoint. // -// This function writes at most |len| bytes, including the NUL byte. If |buf| +// This function writes at most `len` bytes, including the NUL byte. If `buf` // is NULL, it writes nothing and returns the number of bytes in the // output, excluding the NUL byte that would be required for the full UTF-8 // output. // // This function may return -1 if an error occurs for any reason, including the -// value not being a recognized string type, |len| being of insufficient size to +// value not being a recognized string type, `len` being of insufficient size to // hold the full UTF-8 encoding and NUL byte, memory allocation failures, an -// object with type |obj| not existing in |name|, or if the UTF-8 encoding of +// object with type `obj` not existing in `name`, or if the UTF-8 encoding of // the string contains a zero byte. OPENSSL_EXPORT int X509_NAME_get_text_by_OBJ(const X509_NAME *name, const ASN1_OBJECT *obj, char *buf, int len); -// X509_NAME_get_text_by_NID behaves like |X509_NAME_get_text_by_OBJ| except it -// finds an attribute of type |nid|, which should be one of the |NID_*| +// X509_NAME_get_text_by_NID behaves like `X509_NAME_get_text_by_OBJ` except it +// finds an attribute of type `nid`, which should be one of the `NID_*` // constants. OPENSSL_EXPORT int X509_NAME_get_text_by_NID(const X509_NAME *name, int nid, char *buf, int len); @@ -5117,56 +5117,56 @@ OPENSSL_EXPORT X509_STORE_CTX *X509_STORE_CTX_get0_parent_ctx( const X509_STORE_CTX *ctx); -// X509_OBJECT_free_contents sets |obj| to the empty object, freeing any values +// X509_OBJECT_free_contents sets `obj` to the empty object, freeing any values // that were previously there. // // TODO(davidben): Unexport this function after rust-openssl is fixed to no // longer call it. OPENSSL_EXPORT void X509_OBJECT_free_contents(X509_OBJECT *obj); -// X509_LOOKUP_free releases memory associated with |ctx|. This function should +// X509_LOOKUP_free releases memory associated with `ctx`. This function should // never be used outside the library. No function in the public API hands -// ownership of an |X509_LOOKUP| to the caller. +// ownership of an `X509_LOOKUP` to the caller. // // TODO(davidben): Unexport this function after rust-openssl is fixed to no // longer call it. OPENSSL_EXPORT void X509_LOOKUP_free(X509_LOOKUP *ctx); -// X509_STORE_CTX_cleanup resets |ctx| to the empty state. +// X509_STORE_CTX_cleanup resets `ctx` to the empty state. // -// This function is a remnant of when |X509_STORE_CTX| was stack-allocated and -// should not be used. If releasing |ctx|, call |X509_STORE_CTX_free|. If -// reusing |ctx| for a new verification, release the old one and create a new +// This function is a remnant of when `X509_STORE_CTX` was stack-allocated and +// should not be used. If releasing `ctx`, call `X509_STORE_CTX_free`. If +// reusing `ctx` for a new verification, release the old one and create a new // one. OPENSSL_EXPORT void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx); // X509V3_add_standard_extensions returns one. OPENSSL_EXPORT int X509V3_add_standard_extensions(void); -// The following symbols are legacy aliases for |X509_STORE_CTX| functions. +// The following symbols are legacy aliases for `X509_STORE_CTX` functions. #define X509_STORE_get_by_subject X509_STORE_CTX_get_by_subject #define X509_STORE_get1_certs X509_STORE_CTX_get1_certs #define X509_STORE_get1_crls X509_STORE_CTX_get1_crls -// X509_STORE_CTX_get_chain is a legacy alias for |X509_STORE_CTX_get0_chain|. +// X509_STORE_CTX_get_chain is a legacy alias for `X509_STORE_CTX_get0_chain`. OPENSSL_EXPORT STACK_OF(X509) *X509_STORE_CTX_get_chain( const X509_STORE_CTX *ctx); // X509_STORE_CTX_trusted_stack is a deprecated alias for -// |X509_STORE_CTX_set0_trusted_stack|. +// `X509_STORE_CTX_set0_trusted_stack`. OPENSSL_EXPORT void X509_STORE_CTX_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); typedef int (*X509_STORE_CTX_verify_cb)(int, X509_STORE_CTX *); -// X509_STORE_CTX_set_verify_cb configures a callback function for |ctx| that is -// called multiple times during |X509_verify_cert|. The callback returns zero to -// fail verification and one to proceed. Typically, it will return |ok|, which -// preserves the default behavior. Returning one when |ok| is zero will proceed -// past some error. The callback may inspect |ctx| and the error queue to +// X509_STORE_CTX_set_verify_cb configures a callback function for `ctx` that is +// called multiple times during `X509_verify_cert`. The callback returns zero to +// fail verification and one to proceed. Typically, it will return `ok`, which +// preserves the default behavior. Returning one when `ok` is zero will proceed +// past some error. The callback may inspect `ctx` and the error queue to // attempt to determine the current stage of certificate verification, but this // is often unreliable. When synthesizing an error, callbacks should use -// |X509_STORE_CTX_set_error| to set a corresponding error. +// `X509_STORE_CTX_set_error` to set a corresponding error. // // WARNING: Do not use this function. It is extremely fragile and unpredictable. // This callback exposes implementation details of certificate verification, @@ -5174,36 +5174,36 @@ // can introduce vulnerabilities if making incorrect assumptions about when the // callback is called. Some errors, when suppressed, may implicitly suppress // other errors due to internal implementation details. Additionally, overriding -// |ok| may leave |ctx| in an inconsistent state and break invariants. +// `ok` may leave `ctx` in an inconsistent state and break invariants. // // Instead, customize certificate verification by configuring options on the -// |X509_STORE_CTX| before verification, or applying additional checks after -// |X509_verify_cert| completes successfully. +// `X509_STORE_CTX` before verification, or applying additional checks after +// `X509_verify_cert` completes successfully. OPENSSL_EXPORT void X509_STORE_CTX_set_verify_cb( X509_STORE_CTX *ctx, int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); -// X509_STORE_set_verify_cb acts like |X509_STORE_CTX_set_verify_cb| but sets -// the verify callback for any |X509_STORE_CTX| created from this |X509_STORE| +// X509_STORE_set_verify_cb acts like `X509_STORE_CTX_set_verify_cb` but sets +// the verify callback for any `X509_STORE_CTX` created from this `X509_STORE` // -// Do not use this function. See |X509_STORE_CTX_set_verify_cb| for details. +// Do not use this function. See `X509_STORE_CTX_set_verify_cb` for details. OPENSSL_EXPORT void X509_STORE_set_verify_cb( X509_STORE *store, X509_STORE_CTX_verify_cb verify_cb); // X509_STORE_set_verify_cb_func is a deprecated alias for -// |X509_STORE_set_verify_cb|. +// `X509_STORE_set_verify_cb`. #define X509_STORE_set_verify_cb_func(store, func) \ X509_STORE_set_verify_cb((store), (func)) -// X509_STORE_CTX_set_chain configures |ctx| to use |sk| for untrusted +// X509_STORE_CTX_set_chain configures `ctx` to use `sk` for untrusted // intermediate certificates to use in verification. This function is redundant -// with the |chain| parameter of |X509_STORE_CTX_init|. Use the parameter +// with the `chain` parameter of `X509_STORE_CTX_init`. Use the parameter // instead. // // WARNING: Despite the similar name, this function is unrelated to -// |X509_STORE_CTX_get0_chain|. +// `X509_STORE_CTX_get0_chain`. // -// WARNING: This function saves a pointer to |sk| without copying or -// incrementing reference counts. |sk| must outlive |ctx| and may not be mutated +// WARNING: This function saves a pointer to `sk` without copying or +// incrementing reference counts. `sk` must outlive `ctx` and may not be mutated // for the duration of the certificate verification. OPENSSL_EXPORT void X509_STORE_CTX_set_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); @@ -5219,43 +5219,43 @@ // always enabled. #define X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS 0 -// X509_STORE_get0_objects returns a non-owning pointer of |store|'s internal +// X509_STORE_get0_objects returns a non-owning pointer of `store`'s internal // object list. Although this function is not const, callers must not modify // the result of this function. // -// WARNING: This function is not thread-safe. If |store| is shared across +// WARNING: This function is not thread-safe. If `store` is shared across // multiple threads, callers cannot safely inspect the result of this function, // because another thread may have concurrently added to it. In particular, -// |X509_LOOKUP_add_dir| treats this list as a cache and may add to it in the +// `X509_LOOKUP_add_dir` treats this list as a cache and may add to it in the // course of certificate verification. This API additionally prevents fixing -// some quadratic worst-case behavior in |X509_STORE| and may be removed in the -// future. Use |X509_STORE_get1_objects| instead. +// some quadratic worst-case behavior in `X509_STORE` and may be removed in the +// future. Use `X509_STORE_get1_objects` instead. OPENSSL_EXPORT STACK_OF(X509_OBJECT) *X509_STORE_get0_objects( X509_STORE *store); -// X509_PURPOSE_get_by_sname returns the |X509_PURPOSE_*| constant corresponding -// a short name |sname|, or -1 if |sname| was not recognized. +// X509_PURPOSE_get_by_sname returns the `X509_PURPOSE_*` constant corresponding +// a short name `sname`, or -1 if `sname` was not recognized. // -// Use |X509_PURPOSE_*| constants directly instead. The short names used by this +// Use `X509_PURPOSE_*` constants directly instead. The short names used by this // function look like "sslserver" or "smimeencrypt", so they do not make // especially good APIs. // // This function differs from OpenSSL, which returns an "index" to be passed to -// |X509_PURPOSE_get0|, followed by |X509_PURPOSE_get_id|, to finally obtain an -// |X509_PURPOSE_*| value suitable for use with |X509_VERIFY_PARAM_set_purpose|. +// `X509_PURPOSE_get0`, followed by `X509_PURPOSE_get_id`, to finally obtain an +// `X509_PURPOSE_*` value suitable for use with `X509_VERIFY_PARAM_set_purpose`. OPENSSL_EXPORT int X509_PURPOSE_get_by_sname(const char *sname); -// X509_PURPOSE_get0 returns the |X509_PURPOSE| object corresponding to |id|, -// which should be one of the |X509_PURPOSE_*| constants, or NULL if none +// X509_PURPOSE_get0 returns the `X509_PURPOSE` object corresponding to `id`, +// which should be one of the `X509_PURPOSE_*` constants, or NULL if none // exists. // // This function differs from OpenSSL, which takes an "index", returned from -// |X509_PURPOSE_get_by_sname|. In BoringSSL, indices and |X509_PURPOSE_*| IDs +// `X509_PURPOSE_get_by_sname`. In BoringSSL, indices and `X509_PURPOSE_*` IDs // are the same. OPENSSL_EXPORT const X509_PURPOSE *X509_PURPOSE_get0(int id); -// X509_PURPOSE_get_id returns |purpose|'s ID. This will be one of the -// |X509_PURPOSE_*| constants. +// X509_PURPOSE_get_id returns `purpose`'s ID. This will be one of the +// `X509_PURPOSE_*` constants. OPENSSL_EXPORT int X509_PURPOSE_get_id(const X509_PURPOSE *purpose); // The following constants are values for the legacy Netscape certificate type
diff --git a/include/openssl/x509v3.h b/include/openssl/x509v3.h index 3e8a7be..838e855 100644 --- a/include/openssl/x509v3.h +++ b/include/openssl/x509v3.h
@@ -46,7 +46,7 @@ // Deprecated constants. -// The following constants are legacy aliases for |X509v3_KU_*|. They are +// The following constants are legacy aliases for `X509v3_KU_*`. They are // defined here instead of in <openssl/x509.h> because NSS's public headers use // the same symbols. Some callers have inadvertently relied on the conflicts // only being defined in this header.
diff --git a/include/openssl/xwing.h b/include/openssl/xwing.h index a270637..59f884b 100644 --- a/include/openssl/xwing.h +++ b/include/openssl/xwing.h
@@ -54,29 +54,29 @@ // XWING_generate_key generates a random public/private key pair, writes the -// encoded public key to |out_encoded_public_key| and the private key to -// |out_private_key|. Returns one on success and zero on error. +// encoded public key to `out_encoded_public_key` and the private key to +// `out_private_key`. Returns one on success and zero on error. OPENSSL_EXPORT int XWING_generate_key( uint8_t out_encoded_public_key[XWING_PUBLIC_KEY_BYTES], struct XWING_private_key *out_private_key); -// XWING_public_from_private sets |out_encoded_public_key| to the public key -// that corresponds to |private_key|. Returns one on success and zero on error. +// XWING_public_from_private sets `out_encoded_public_key` to the public key +// that corresponds to `private_key`. Returns one on success and zero on error. OPENSSL_EXPORT int XWING_public_from_private( uint8_t out_encoded_public_key[XWING_PUBLIC_KEY_BYTES], const struct XWING_private_key *private_key); -// XWING_encap encapsulates a random shared secret for |encoded_public_key|, -// writes the ciphertext to |out_ciphertext|, and writes the random shared -// secret to |out_shared_secret|. Returns one on success and zero on error. +// XWING_encap encapsulates a random shared secret for `encoded_public_key`, +// writes the ciphertext to `out_ciphertext`, and writes the random shared +// secret to `out_shared_secret`. Returns one on success and zero on error. OPENSSL_EXPORT int XWING_encap( uint8_t out_ciphertext[XWING_CIPHERTEXT_BYTES], uint8_t out_shared_secret[XWING_SHARED_SECRET_BYTES], const uint8_t encoded_public_key[XWING_PUBLIC_KEY_BYTES]); // XWING_encap_external_entropy encapsulates the shared secret for the given -// |eseed| entropy using |encoded_public_key|, writes the ciphertext to -// |out_ciphertext|, and writes the random shared secret to |out_shared_secret|. +// `eseed` entropy using `encoded_public_key`, writes the ciphertext to +// `out_ciphertext`, and writes the random shared secret to `out_shared_secret`. // Returns one on success and zero on error. OPENSSL_EXPORT int XWING_encap_external_entropy( uint8_t out_ciphertext[XWING_CIPHERTEXT_BYTES], @@ -84,8 +84,8 @@ const uint8_t encoded_public_key[XWING_PUBLIC_KEY_BYTES], const uint8_t eseed[64]); -// XWING_decap decapsulates a shared secret from |ciphertext| using -// |private_key| and writes it to |out_shared_secret|. Returns one on success +// XWING_decap decapsulates a shared secret from `ciphertext` using +// `private_key` and writes it to `out_shared_secret`. Returns one on success // and zero on error. OPENSSL_EXPORT int XWING_decap( uint8_t out_shared_secret[XWING_SHARED_SECRET_BYTES], @@ -94,16 +94,16 @@ // Serialisation of keys. -// XWING_marshal_private_key serializes |private_key| to |out| in the standard +// XWING_marshal_private_key serializes `private_key` to `out` in the standard // format for X-Wing private keys. It returns one on success or zero on // allocation error. OPENSSL_EXPORT int XWING_marshal_private_key( CBB *out, const struct XWING_private_key *private_key); // XWING_parse_private_key parses a private key in the standard format for -// X-Wing private keys from |in| and writes the result to |out_public_key|. It +// X-Wing private keys from `in` and writes the result to `out_public_key`. It // returns one on success or zero on parse error or if there are trailing bytes -// in |in|. +// in `in`. OPENSSL_EXPORT int XWING_parse_private_key( struct XWING_private_key *out_private_key, CBS *in);