Documentation: Change |...| to `...` for code references in comments 15/15 This CL includes the result of running util/update_comment_style.py over all *.cc.inc files in crypto/, and fixing omissions manually if necessary. Bug: 42290410 Change-Id: Idee5b840aa3e5efc1b4ecd35ed83da336a6a6964 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/96154 Commit-Queue: Lily Chen <chlily@google.com> Reviewed-by: David Benjamin <davidben@google.com>
diff --git a/crypto/fipsmodule/aes/aes.cc.inc b/crypto/fipsmodule/aes/aes.cc.inc index 56a110f..f18906b 100644 --- a/crypto/fipsmodule/aes/aes.cc.inc +++ b/crypto/fipsmodule/aes/aes.cc.inc
@@ -21,9 +21,9 @@ using namespace bssl; // Be aware that different sets of AES functions use incompatible key -// representations, varying in format of the key schedule, the |AES_KEY.rounds| +// representations, varying in format of the key schedule, the `AES_KEY.rounds` // value, or both. Therefore they cannot mix. Also, on AArch64, the plain-C -// code, above, is incompatible with the |aes_hw_*| functions. +// code, above, is incompatible with the `aes_hw_*` functions. bcm_infallible bssl::BCM_aes_encrypt(const uint8_t *in, uint8_t *out, const AES_KEY *key) { @@ -84,8 +84,8 @@ } #if defined(HWAES) && (defined(OPENSSL_X86) || defined(OPENSSL_X86_64)) -// On x86 and x86_64, |aes_hw_set_decrypt_key|, we implement -// |aes_hw_encrypt_key_to_decrypt_key| in assembly and rely on C code to combine +// On x86 and x86_64, `aes_hw_set_decrypt_key`, we implement +// `aes_hw_encrypt_key_to_decrypt_key` in assembly and rely on C code to combine // the operations. int bssl::aes_hw_set_decrypt_key(const uint8_t *user_key, int bits, AES_KEY *key) { @@ -107,7 +107,7 @@ #endif #if defined(VPAES) && defined(OPENSSL_X86) -// On x86, there is no |vpaes_ctr32_encrypt_blocks|, so we implement it +// On x86, there is no `vpaes_ctr32_encrypt_blocks`, so we implement it // ourselves. This avoids all callers needing to account for a missing function. void bssl::vpaes_ctr32_encrypt_blocks(const uint8_t *in, uint8_t *out, size_t blocks, const AES_KEY *key, @@ -131,7 +131,7 @@ uint8_t *out, size_t blocks, const AES_KEY *key, const uint8_t ivec[16]) { - // |bsaes_ctr32_encrypt_blocks| is faster than |vpaes_ctr32_encrypt_blocks|, + // `bsaes_ctr32_encrypt_blocks` is faster than `vpaes_ctr32_encrypt_blocks`, // but it takes at least one full 8-block batch to amortize the conversion. if (blocks < 8) { vpaes_ctr32_encrypt_blocks(in, out, blocks, key, ivec); @@ -140,9 +140,9 @@ size_t bsaes_blocks = blocks; if (bsaes_blocks % 8 < 6) { - // |bsaes_ctr32_encrypt_blocks| internally works in 8-block batches. If the + // `bsaes_ctr32_encrypt_blocks` internally works in 8-block batches. If the // final batch is too small (under six blocks), it is faster to loop over - // |vpaes_encrypt|. Round |bsaes_blocks| down to a multiple of 8. + // `vpaes_encrypt`. Round `bsaes_blocks` down to a multiple of 8. bsaes_blocks -= bsaes_blocks % 8; } @@ -160,7 +160,7 @@ uint32_t ctr = CRYPTO_load_u32_be(ivec + 12) + bsaes_blocks; CRYPTO_store_u32_be(new_ivec + 12, ctr); - // Finish any remaining blocks with |vpaes_ctr32_encrypt_blocks|. + // Finish any remaining blocks with `vpaes_ctr32_encrypt_blocks`. vpaes_ctr32_encrypt_blocks(in, out, blocks, key, new_ivec); } #endif // BSAES
diff --git a/crypto/fipsmodule/aes/aes_nohw.cc.inc b/crypto/fipsmodule/aes/aes_nohw.cc.inc index 20f6a6b..0c31251 100644 --- a/crypto/fipsmodule/aes/aes_nohw.cc.inc +++ b/crypto/fipsmodule/aes/aes_nohw.cc.inc
@@ -45,18 +45,18 @@ // shifts match the operations themselves, which makes them reversed in a // little-endian, left-to-right reading. // -// Eight |aes_word_t|s contain |AES_NOHW_BATCH_SIZE| blocks. The bits in an -// |aes_word_t| are divided into 16 consecutive groups of |AES_NOHW_BATCH_SIZE| +// Eight `aes_word_t`s contain `AES_NOHW_BATCH_SIZE` blocks. The bits in an +// `aes_word_t` are divided into 16 consecutive groups of `AES_NOHW_BATCH_SIZE` // bits each, each corresponding to a byte in an AES block in column-major // order (AES's byte order). We refer to these as "logical bytes". Note, in the // 32-bit and 64-bit implementations, they are smaller than a byte. (The // contents of a logical byte will be described later.) // -// MSVC does not support C bit operators on |__m128i|, so the wrapper functions -// |aes_nohw_and|, etc., should be used instead. Note |aes_nohw_shift_left| and -// |aes_nohw_shift_right| measure the shift in logical bytes. That is, the shift -// value ranges from 0 to 15 independent of |aes_word_t| and -// |AES_NOHW_BATCH_SIZE|. +// MSVC does not support C bit operators on `__m128i`, so the wrapper functions +// `aes_nohw_and`, etc., should be used instead. Note `aes_nohw_shift_left` and +// `aes_nohw_shift_right` measure the shift in logical bytes. That is, the shift +// value ranges from 0 to 15 independent of `aes_word_t` and +// `AES_NOHW_BATCH_SIZE`. // // This ordering is different from https://eprint.iacr.org/2009/129.pdf, which // uses row-major order. Matching the AES order was easier to reason about, and @@ -100,7 +100,7 @@ a, _mm_set_epi32(0xffffffff, 0xffffffff, 0xffffffff, 0xffffffff)); } -// These are macros because parameters to |_mm_slli_si128| and |_mm_srli_si128| +// These are macros because parameters to `_mm_slli_si128` and `_mm_srli_si128` // must be constants. #define aes_nohw_shift_left(/* aes_word_t */ a, /* const */ i) \ _mm_slli_si128((a), (i)) @@ -158,8 +158,8 @@ // // This implementation uses three representations for AES blocks. First, the // public API represents blocks as uint8_t[16] in the usual way. Second, most -// AES steps are evaluated in bitsliced form, stored in an |AES_NOHW_BATCH|. -// This stores |AES_NOHW_BATCH_SIZE| blocks in bitsliced order. For 64-bit words +// AES steps are evaluated in bitsliced form, stored in an `AES_NOHW_BATCH`. +// This stores `AES_NOHW_BATCH_SIZE` blocks in bitsliced order. For 64-bit words // containing bitsliced blocks a, b, c, d, this would be as follows (vertical // bars divide logical bytes): // @@ -172,10 +172,10 @@ // Finally, an individual block may be stored as an intermediate form in an // aes_word_t[AES_NOHW_BLOCK_WORDS]. In this form, we permute the bits in each // block, so that block[0]'s ith logical byte contains least-significant -// |AES_NOHW_BATCH_SIZE| bits of byte i, block[1] contains the next group of -// |AES_NOHW_BATCH_SIZE| bits, and so on. We refer to this transformation as +// `AES_NOHW_BATCH_SIZE` bits of byte i, block[1] contains the next group of +// `AES_NOHW_BATCH_SIZE` bits, and so on. We refer to this transformation as // "compacting" the block. Note this is no-op with 128-bit words because then -// |AES_NOHW_BLOCK_WORDS| is one and |AES_NOHW_BATCH_SIZE| is eight. For 64-bit +// `AES_NOHW_BLOCK_WORDS` is one and `AES_NOHW_BATCH_SIZE` is eight. For 64-bit // words, one block would be stored in two words: // // block[0] = a0 a1 a2 a3 | a8 a9 a10 a11 | a16 a17 a18 a19 ... @@ -197,40 +197,40 @@ // batch.w[3] = a3 b3 c3 d3 | a11 b11 c11 d11 | a19 b19 c19 d19 ... // // Note also that bitwise operations and (logical) byte permutations on an -// |aes_word_t| work equally for the bitsliced and compact words. +// `aes_word_t` work equally for the bitsliced and compact words. // -// We use the compact form in the |AES_KEY| representation to save work -// inflating round keys into |AES_NOHW_BATCH|. The compact form also exists -// temporarily while moving blocks in or out of an |AES_NOHW_BATCH|, immediately -// before or after |aes_nohw_transpose|. +// We use the compact form in the `AES_KEY` representation to save work +// inflating round keys into `AES_NOHW_BATCH`. The compact form also exists +// temporarily while moving blocks in or out of an `AES_NOHW_BATCH`, immediately +// before or after `aes_nohw_transpose`. #define AES_NOHW_BLOCK_WORDS (16 / sizeof(aes_word_t)) -// An AES_NOHW_BATCH stores |AES_NOHW_BATCH_SIZE| blocks. Unless otherwise +// An AES_NOHW_BATCH stores `AES_NOHW_BATCH_SIZE` blocks. Unless otherwise // specified, it is in bitsliced form. typedef struct { aes_word_t w[8]; } AES_NOHW_BATCH; // An AES_NOHW_SCHEDULE is an expanded bitsliced AES key schedule. It is -// suitable for encryption or decryption. It is as large as |AES_NOHW_BATCH| -// |AES_KEY|s so it should not be used as a long-term key representation. +// suitable for encryption or decryption. It is as large as `AES_NOHW_BATCH` +// `AES_KEY`s so it should not be used as a long-term key representation. typedef struct { // keys is an array of batches, one for each round key. Each batch stores - // |AES_NOHW_BATCH_SIZE| copies of the round key in bitsliced form. + // `AES_NOHW_BATCH_SIZE` copies of the round key in bitsliced form. AES_NOHW_BATCH keys[AES_MAXNR + 1]; } AES_NOHW_SCHEDULE; -// aes_nohw_batch_set sets the |i|th block of |batch| to |in|. |batch| is in +// aes_nohw_batch_set sets the `i`th block of `batch` to `in`. `batch` is in // compact form. static void aes_nohw_batch_set(AES_NOHW_BATCH *batch, const aes_word_t in[AES_NOHW_BLOCK_WORDS], size_t i) { - // Note the words are interleaved. The order comes from |aes_nohw_transpose|. - // If |i| is zero and this is the 64-bit implementation, in[0] contains bits + // Note the words are interleaved. The order comes from `aes_nohw_transpose`. + // If `i` is zero and this is the 64-bit implementation, in[0] contains bits // 0-3 and in[1] contains bits 4-7. We place in[0] at w[0] and in[1] at // w[4] so that bits 0 and 4 are in the correct position. (In general, bits - // along diagonals of |AES_NOHW_BATCH_SIZE| by |AES_NOHW_BATCH_SIZE| squares + // along diagonals of `AES_NOHW_BATCH_SIZE` by `AES_NOHW_BATCH_SIZE` squares // will be correctly placed.) assert(i < AES_NOHW_BATCH_SIZE); #if defined(OPENSSL_SSE2) @@ -246,7 +246,7 @@ #endif } -// aes_nohw_batch_get writes the |i|th block of |batch| to |out|. |batch| is in +// aes_nohw_batch_get writes the `i`th block of `batch` to `out`. `batch` is in // compact form. static void aes_nohw_batch_get(const AES_NOHW_BATCH *batch, aes_word_t out[AES_NOHW_BLOCK_WORDS], size_t i) { @@ -265,8 +265,8 @@ } #if !defined(OPENSSL_SSE2) -// aes_nohw_delta_swap returns |a| with bits |a & mask| and -// |a & (mask << shift)| swapped. |mask| and |mask << shift| may not overlap. +// aes_nohw_delta_swap returns `a` with bits |a & mask| and +// |a & (mask << shift)| swapped. `mask` and |mask << shift| may not overlap. static aes_word_t aes_nohw_delta_swap(aes_word_t a, aes_word_t mask, aes_word_t shift) { // See @@ -276,8 +276,8 @@ } // In the 32-bit and 64-bit implementations, a block spans multiple words. -// |aes_nohw_compact_block| must permute bits across different words. First we -// implement |aes_nohw_compact_word| which performs a smaller version of the +// `aes_nohw_compact_block` must permute bits across different words. First we +// implement `aes_nohw_compact_word` which performs a smaller version of the // transformation which stays within a single word. // // These transformations are generalizations of the output of @@ -301,7 +301,7 @@ } static uint64_t aes_nohw_uncompact_word(uint64_t a) { - // Reverse the steps of |aes_nohw_uncompact_word|. + // Reverse the steps of `aes_nohw_uncompact_word`. a = aes_nohw_delta_swap(a, UINT64_C(0x00000000ffff0000), 16); a = aes_nohw_delta_swap(a, UINT64_C(0x0000ff000000ff00), 8); a = aes_nohw_delta_swap(a, UINT64_C(0x00f000f000f000f0), 4); @@ -324,7 +324,7 @@ } static uint32_t aes_nohw_uncompact_word(uint32_t a) { - // Reverse the steps of |aes_nohw_uncompact_word|. + // Reverse the steps of `aes_nohw_uncompact_word`. a = aes_nohw_delta_swap(a, 0x0000f0f0, 12); a = aes_nohw_delta_swap(a, 0x00cc00cc, 6); return a; @@ -406,11 +406,11 @@ } // aes_nohw_swap_bits is a variation on a delta swap. It swaps the bits in -// |*a & (mask << shift)| with the bits in |*b & mask|. |mask| and -// |mask << shift| must not overlap. |mask| is specified as a |uint32_t|, but it -// is repeated to the full width of |aes_word_t|. +// `*a & (mask << shift)` with the bits in `*b & mask`. `mask` and +// `mask << shift` must not overlap. `mask` is specified as a `uint32_t`, but it +// is repeated to the full width of `aes_word_t`. #if defined(OPENSSL_SSE2) -// This must be a macro because |_mm_srli_epi32| and |_mm_slli_epi32| require +// This must be a macro because `_mm_srli_epi32` and `_mm_slli_epi32` require // constant shift values. #define aes_nohw_swap_bits(/*__m128i* */ a, /*__m128i* */ b, \ /* uint32_t */ mask, /* const */ shift) \ @@ -437,7 +437,7 @@ } #endif // OPENSSL_SSE2 -// aes_nohw_transpose converts |batch| to and from bitsliced form. It divides +// aes_nohw_transpose converts `batch` to and from bitsliced form. It divides // the 8 × word_size bits into AES_NOHW_BATCH_SIZE × AES_NOHW_BATCH_SIZE squares // and transposes each square. static void aes_nohw_transpose(AES_NOHW_BATCH *batch) { @@ -464,8 +464,8 @@ #endif } -// aes_nohw_to_batch initializes |out| with the |num_blocks| blocks from |in|. -// |num_blocks| must be at most |AES_NOHW_BATCH|. +// aes_nohw_to_batch initializes `out` with the `num_blocks` blocks from `in`. +// `num_blocks` must be at most `AES_NOHW_BATCH`. static void aes_nohw_to_batch(AES_NOHW_BATCH *out, const uint8_t *in, size_t num_blocks) { // Don't leave unused blocks uninitialized. @@ -480,8 +480,8 @@ aes_nohw_transpose(out); } -// aes_nohw_to_batch writes the first |num_blocks| blocks in |batch| to |out|. -// |num_blocks| must be at most |AES_NOHW_BATCH|. +// aes_nohw_to_batch writes the first `num_blocks` blocks in `batch` to `out`. +// `num_blocks` must be at most `AES_NOHW_BATCH`. static void aes_nohw_from_batch(uint8_t *out, size_t num_blocks, const AES_NOHW_BATCH *batch) { AES_NOHW_BATCH copy = *batch; @@ -696,8 +696,8 @@ aes_nohw_sub_bytes_inv_affine(batch); } -// aes_nohw_rotate_cols_right returns |v| with the columns in each row rotated -// to the right by |n|. This is a macro because |aes_nohw_shift_*| require +// aes_nohw_rotate_cols_right returns `v` with the columns in each row rotated +// to the right by `n`. This is a macro because `aes_nohw_shift_*` require // constant shift counts in the SSE2 implementation. #define aes_nohw_rotate_cols_right(/* aes_word_t */ v, /* const */ n) \ (aes_nohw_or(aes_nohw_shift_right((v), (n)*4), \ @@ -729,7 +729,7 @@ } } -// aes_nohw_rotate_rows_down returns |v| with the rows in each column rotated +// aes_nohw_rotate_rows_down returns `v` with the rows in each column rotated // down by one. static aes_word_t aes_nohw_rotate_rows_down(aes_word_t v) { #if defined(OPENSSL_SSE2) @@ -742,7 +742,7 @@ #endif } -// aes_nohw_rotate_rows_twice returns |v| with the rows in each column rotated +// aes_nohw_rotate_rows_twice returns `v` with the rows in each column rotated // by two. static aes_word_t aes_nohw_rotate_rows_twice(aes_word_t v) { #if defined(OPENSSL_SSE2) @@ -910,8 +910,8 @@ static const uint8_t aes_nohw_rcon[10] = {0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, 0x1b, 0x36}; -// aes_nohw_rcon_slice returns the |i|th group of |AES_NOHW_BATCH_SIZE| bits in -// |rcon|, stored in a |aes_word_t|. +// aes_nohw_rcon_slice returns the `i`th group of `AES_NOHW_BATCH_SIZE` bits in +// `rcon`, stored in a `aes_word_t`. static aes_word_t aes_nohw_rcon_slice(uint8_t rcon, size_t i) { rcon = (rcon >> (i * AES_NOHW_BATCH_SIZE)) & ((1 << AES_NOHW_BATCH_SIZE) - 1); #if defined(OPENSSL_SSE2) @@ -944,7 +944,7 @@ aes_nohw_sub_block(sub, block); uint8_t rcon = aes_nohw_rcon[i - 1]; for (size_t j = 0; j < AES_NOHW_BLOCK_WORDS; j++) { - // Incorporate |rcon| and the transformed word into the first word. + // Incorporate `rcon` and the transformed word into the first word. block[j] = aes_nohw_xor(block[j], aes_nohw_rcon_slice(rcon, j)); block[j] = aes_nohw_xor( block[j], @@ -971,9 +971,9 @@ // We maintain a sliding window of two blocks, filled to 1.5 blocks at a time. // We loop below every three blocks or two key schedule iterations. // - // On entry to the loop, |block1| and the first half of |block2| contain the - // previous key schedule iteration. |block1| has been written to |key|, but - // |block2| has not as it is incomplete. + // On entry to the loop, `block1` and the first half of `block2` contain the + // previous key schedule iteration. `block1` has been written to `key`, but + // `block2` has not as it is incomplete. aes_nohw_compact_block(block1, in); memcpy(key->rd_key, block1, 16); @@ -987,17 +987,17 @@ uint8_t rcon = aes_nohw_rcon[2 * i]; for (size_t j = 0; j < AES_NOHW_BLOCK_WORDS; j++) { // Compute the first two words of the next key schedule iteration, which - // go in the second half of |block2|. The first two words of the previous - // iteration are in the first half of |block1|. Apply |rcon| here too + // go in the second half of `block2`. The first two words of the previous + // iteration are in the first half of `block1`. Apply `rcon` here too // because the shifts match. block2[j] = aes_nohw_or( block2[j], aes_nohw_shift_left( aes_nohw_xor(block1[j], aes_nohw_rcon_slice(rcon, j)), 8)); // Incorporate the transformed word and propagate. Note the last word of - // the previous iteration corresponds to the second word of |copy|. This + // the previous iteration corresponds to the second word of `copy`. This // is incorporated into the first word of the next iteration, or the third - // word of |block2|. + // word of `block2`. block2[j] = aes_nohw_xor( block2[j], aes_nohw_and(aes_nohw_shift_left( aes_nohw_rotate_rows_down(sub[j]), 4), @@ -1006,12 +1006,12 @@ block2[j], aes_nohw_and(aes_nohw_shift_left(block2[j], 4), AES_NOHW_COL3_MASK)); - // Compute the remaining four words, which fill |block1|. Begin by moving + // Compute the remaining four words, which fill `block1`. Begin by moving // the corresponding words of the previous iteration: the second half of - // |block1| and the first half of |block2|. + // `block1` and the first half of `block2`. block1[j] = aes_nohw_shift_right(block1[j], 8); block1[j] = aes_nohw_or(block1[j], aes_nohw_shift_left(block2[j], 8)); - // Incorporate the second word, computed previously in |block2|, and + // Incorporate the second word, computed previously in `block2`, and // propagate. block1[j] = aes_nohw_xor(block1[j], aes_nohw_shift_right(block2[j], 12)); aes_word_t v = block1[j]; @@ -1020,7 +1020,7 @@ block1[j] = aes_nohw_xor(block1[j], aes_nohw_shift_left(v, 12)); } - // This completes two round keys. Note half of |block2| was computed in the + // This completes two round keys. Note half of `block2` was computed in the // previous loop iteration but was not yet output. memcpy(key->rd_key + 4 * (3 * i + 1), block2, 16); memcpy(key->rd_key + 4 * (3 * i + 2), block1, 16); @@ -1029,12 +1029,12 @@ rcon = aes_nohw_rcon[2 * i + 1]; for (size_t j = 0; j < AES_NOHW_BLOCK_WORDS; j++) { // Compute the first four words of the next key schedule iteration in - // |block2|. Begin by moving the corresponding words of the previous - // iteration: the second half of |block2| and the first half of |block1|. + // `block2`. Begin by moving the corresponding words of the previous + // iteration: the second half of `block2` and the first half of `block1`. block2[j] = aes_nohw_shift_right(block2[j], 8); block2[j] = aes_nohw_or(block2[j], aes_nohw_shift_left(block1[j], 8)); // Incorporate rcon and the transformed word. Note the last word of the - // previous iteration corresponds to the last word of |copy|. + // previous iteration corresponds to the last word of `copy`. block2[j] = aes_nohw_xor(block2[j], aes_nohw_rcon_slice(rcon, j)); block2[j] = aes_nohw_xor( block2[j], @@ -1045,9 +1045,9 @@ block2[j] = aes_nohw_xor(block2[j], aes_nohw_shift_left(v, 8)); block2[j] = aes_nohw_xor(block2[j], aes_nohw_shift_left(v, 12)); - // Compute the last two words, which go in the first half of |block1|. The + // Compute the last two words, which go in the first half of `block1`. The // last two words of the previous iteration are in the second half of - // |block1|. + // `block1`. block1[j] = aes_nohw_shift_right(block1[j], 8); // Propagate blocks and mask off the excess. block1[j] = aes_nohw_xor(block1[j], aes_nohw_shift_right(block2[j], 12)); @@ -1055,7 +1055,7 @@ block1[j] = aes_nohw_and(block1[j], AES_NOHW_COL01_MASK); } - // |block2| has a complete round key. |block1| will be completed in the next + // `block2` has a complete round key. `block1` will be completed in the next // iteration. memcpy(key->rd_key + 4 * (3 * i + 3), block2, 16); @@ -1082,7 +1082,7 @@ aes_nohw_sub_block(sub, block2); uint8_t rcon = aes_nohw_rcon[i / 2 - 1]; for (size_t j = 0; j < AES_NOHW_BLOCK_WORDS; j++) { - // Incorporate |rcon| and the transformed word into the first word. + // Incorporate `rcon` and the transformed word into the first word. block1[j] = aes_nohw_xor(block1[j], aes_nohw_rcon_slice(rcon, j)); block1[j] = aes_nohw_xor( block1[j], @@ -1178,7 +1178,7 @@ AES_NOHW_SCHEDULE sched; aes_nohw_expand_round_keys(&sched, key); - // Make |AES_NOHW_BATCH_SIZE| copies of |ivec|. + // Make `AES_NOHW_BATCH_SIZE` copies of `ivec`. alignas(AES_NOHW_WORD_SIZE) uint8_t ivs[AES_NOHW_BATCH_SIZE * 16]; alignas(AES_NOHW_WORD_SIZE) uint8_t enc_ivs[AES_NOHW_BATCH_SIZE * 16]; for (size_t i = 0; i < AES_NOHW_BATCH_SIZE; i++) {
diff --git a/crypto/fipsmodule/aes/cbc.cc.inc b/crypto/fipsmodule/aes/cbc.cc.inc index aa9b759..5ed6373 100644 --- a/crypto/fipsmodule/aes/cbc.cc.inc +++ b/crypto/fipsmodule/aes/cbc.cc.inc
@@ -26,7 +26,7 @@ block128_f block) { assert(key != nullptr && ivec != nullptr); if (len == 0) { - // Avoid |ivec| == |iv| in the |memcpy| below, which is not legal in C. + // Avoid `ivec` == `iv` in the `memcpy` below, which is not legal in C. return; } @@ -67,7 +67,7 @@ block128_f block) { assert(key != nullptr && ivec != nullptr); if (len == 0) { - // Avoid |ivec| == |iv| in the |memcpy| below, which is not legal in C. + // Avoid `ivec` == `iv` in the `memcpy` below, which is not legal in C. return; } @@ -75,13 +75,13 @@ const uintptr_t inptr = (uintptr_t) in; const uintptr_t outptr = (uintptr_t) out; - // If |in| and |out| alias, |in| must be ahead. + // If `in` and `out` alias, `in` must be ahead. assert(inptr >= outptr || inptr + len <= outptr); size_t n; alignas(16) uint8_t tmp[16]; if ((inptr >= 32 && outptr <= inptr - 32) || inptr < outptr) { - // If |out| is at least two blocks behind |in| or completely disjoint, there + // If `out` is at least two blocks behind `in` or completely disjoint, there // is no need to decrypt to a temporary block. const uint8_t *iv = ivec; while (len >= 16) {
diff --git a/crypto/fipsmodule/aes/gcm.cc.inc b/crypto/fipsmodule/aes/gcm.cc.inc index 73beb8b..0e6f771 100644 --- a/crypto/fipsmodule/aes/gcm.cc.inc +++ b/crypto/fipsmodule/aes/gcm.cc.inc
@@ -26,7 +26,7 @@ using namespace bssl; // kSizeTWithoutLower4Bits is a mask that can be used to zero the lower four -// bits of a |size_t|. +// bits of a `size_t`. static const size_t kSizeTWithoutLower4Bits = (size_t) -16; @@ -79,7 +79,7 @@ Htable[14].hi = V.hi ^ Htable[6].hi, Htable[14].lo = V.lo ^ Htable[6].lo; Htable[15].hi = V.hi ^ Htable[7].hi, Htable[15].lo = V.lo ^ Htable[7].lo; - // Treat |Htable| as a 16x16 byte table and transpose it. Thus, Htable[i] + // Treat `Htable` as a 16x16 byte table and transpose it. Thus, Htable[i] // contains the i'th byte of j*H for all j. uint8_t *Hbytes = (uint8_t *)Htable; for (int i = 0; i < 16; i++) { @@ -180,7 +180,7 @@ void bssl::CRYPTO_ghash_init(gmult_func *out_mult, ghash_func *out_hash, u128 out_table[16], const uint8_t gcm_key[16]) { - // H is passed to |gcm_init_*| as a pair of byte-swapped, 64-bit values. + // H is passed to `gcm_init_*` as a pair of byte-swapped, 64-bit values. uint64_t H[2] = {CRYPTO_load_u64_be(gcm_key), CRYPTO_load_u64_be(gcm_key + 8)}; @@ -435,7 +435,7 @@ #if defined(HW_GCM) if (key->impl != gcm_separate && len > 0) { - // |hw_gcm_encrypt| may not process all the input given to it. It may + // `hw_gcm_encrypt` may not process all the input given to it. It may // not process *any* of its input if it is deemed too small. size_t bulk = hw_gcm_encrypt(in, out, len, &key->aes, ctx->Yi, ctx->Xi, key->Htable, key->impl); @@ -523,7 +523,7 @@ #if defined(HW_GCM) if (key->impl != gcm_separate && len > 0) { - // |hw_gcm_decrypt| may not process all the input given to it. It may + // `hw_gcm_decrypt` may not process all the input given to it. It may // not process *any* of its input if it is deemed too small. size_t bulk = hw_gcm_decrypt(in, out, len, &key->aes, ctx->Yi, ctx->Xi, key->Htable, key->impl);
diff --git a/crypto/fipsmodule/aes/gcm_nohw.cc.inc b/crypto/fipsmodule/aes/gcm_nohw.cc.inc index a4c6d1c..4af795e 100644 --- a/crypto/fipsmodule/aes/gcm_nohw.cc.inc +++ b/crypto/fipsmodule/aes/gcm_nohw.cc.inc
@@ -40,7 +40,7 @@ // One term every four bits means the largest term is 64/4 = 16, which barely // overflows into the next term. Using one term every five bits would cost 25 // multiplications instead of 16. It is faster to mask off the bottom four - // bits of |a|, giving a largest term of 60/4 = 15, and apply the bottom bits + // bits of `a`, giving a largest term of 60/4 = 15, and apply the bottom bits // separately. uint64_t a0 = a & UINT64_C(0x1111111111111110); uint64_t a1 = a & UINT64_C(0x2222222222222220); @@ -61,7 +61,7 @@ uint128_t c3 = (a0 * (uint128_t)b3) ^ (a1 * (uint128_t)b2) ^ (a2 * (uint128_t)b1) ^ (a3 * (uint128_t)b0); - // Multiply the bottom four bits of |a| with |b|. + // Multiply the bottom four bits of `a` with `b`. uint64_t a0_mask = UINT64_C(0) - (a & 1); uint64_t a1_mask = UINT64_C(0) - ((a >> 1) & 1); uint64_t a2_mask = UINT64_C(0) - ((a >> 2) & 1); @@ -201,7 +201,7 @@ // rev128(X) * rev128(Y) = rev255(X*Y). // // Per Appendix A, we run mulX_POLYVAL. Note this is the same transformation - // applied by |gcm_init_clmul|, etc. Note |Xi| has already been byteswapped. + // applied by `gcm_init_clmul`, etc. Note `Xi` has already been byteswapped. // // See also slide 16 of // https://crypto.stanford.edu/RealWorldCrypto/slides/gueron.pdf @@ -220,12 +220,12 @@ Htable[0].lo ^= carry & 1; Htable[0].hi ^= carry & UINT64_C(0xc200000000000000); - // This implementation does not use the rest of |Htable|. + // This implementation does not use the rest of `Htable`. } static void gcm_polyval_nohw(uint64_t Xi[2], const u128 *H) { - // Karatsuba multiplication. The product of |Xi| and |H| is stored in |r0| - // through |r3|. Note there is no byte or bit reversal because we are + // Karatsuba multiplication. The product of `Xi` and `H` is stored in `r0` + // through `r3`. Note there is no byte or bit reversal because we are // evaluating POLYVAL. uint64_t r0, r1; gcm_mul64_nohw(&r0, &r1, Xi[0], H->lo); @@ -238,8 +238,8 @@ r2 ^= mid1; r1 ^= mid0; - // Now we multiply our 256-bit result by x^-128 and reduce. |r2| and - // |r3| shifts into position and we must multiply |r0| and |r1| by x^-128. We + // Now we multiply our 256-bit result by x^-128 and reduce. `r2` and + // `r3` shifts into position and we must multiply `r0` and `r1` by x^-128. We // have: // // 1 = x^121 + x^126 + x^127 + x^128 @@ -249,7 +249,7 @@ // The x^-7, x^-2, and x^-1 terms shift bits past x^0, which would require // another reduction steps. Instead, we gather the excess bits, incorporate - // them into |r0| and |r1| and reduce once. See slides 17-19 + // them into `r0` and `r1` and reduce once. See slides 17-19 // of https://crypto.stanford.edu/RealWorldCrypto/slides/gueron.pdf. r1 ^= (r0 << 63) ^ (r0 << 62) ^ (r0 << 57);
diff --git a/crypto/fipsmodule/aes/mode_wrappers.cc.inc b/crypto/fipsmodule/aes/mode_wrappers.cc.inc index 34f14b0..5507961 100644 --- a/crypto/fipsmodule/aes/mode_wrappers.cc.inc +++ b/crypto/fipsmodule/aes/mode_wrappers.cc.inc
@@ -39,8 +39,8 @@ CRYPTO_ctr128_encrypt_ctr32(in, out, len, key, ivec, ecount_buf, num, aes_hw_ctr32_encrypt_blocks); } else if (vpaes_capable()) { - // TODO(davidben): On ARM, where |BSAES| is additionally defined, this could - // use |vpaes_ctr32_encrypt_blocks_with_bsaes|. + // TODO(davidben): On ARM, where `BSAES` is additionally defined, this could + // use `vpaes_ctr32_encrypt_blocks_with_bsaes`. CRYPTO_ctr128_encrypt_ctr32(in, out, len, key, ivec, ecount_buf, num, vpaes_ctr32_encrypt_blocks); } else {
diff --git a/crypto/fipsmodule/bn/add.cc.inc b/crypto/fipsmodule/bn/add.cc.inc index 38c7d5b..5c48e44 100644 --- a/crypto/fipsmodule/bn/add.cc.inc +++ b/crypto/fipsmodule/bn/add.cc.inc
@@ -62,7 +62,7 @@ } int bssl::bn_uadd_consttime(BIGNUM *r, const BIGNUM *a, const BIGNUM *b) { - // Widths are public, so we normalize to make |a| the larger one. + // Widths are public, so we normalize to make `a` the larger one. if (a->width < b->width) { const BIGNUM *tmp = a; a = b; @@ -182,8 +182,8 @@ } int bssl::bn_usub_consttime(BIGNUM *r, const BIGNUM *a, const BIGNUM *b) { - // |b| may have more words than |a| given non-minimal inputs, but all words - // beyond |a->width| must then be zero. + // `b` may have more words than `a` given non-minimal inputs, but all words + // beyond `a->width` must then be zero. int b_width = b->width; if (b_width > a->width) { if (!bn_fits_in_words(b, a->width)) {
diff --git a/crypto/fipsmodule/bn/bn.cc.inc b/crypto/fipsmodule/bn/bn.cc.inc index 38dea25..c18efa9 100644 --- a/crypto/fipsmodule/bn/bn.cc.inc +++ b/crypto/fipsmodule/bn/bn.cc.inc
@@ -28,8 +28,8 @@ using namespace bssl; -// BN_MAX_WORDS is the maximum number of words allowed in a |BIGNUM|. It is -// sized so byte and bit counts of a |BIGNUM| always fit in |int|, with room to +// BN_MAX_WORDS is the maximum number of words allowed in a `BIGNUM`. It is +// sized so byte and bit counts of a `BIGNUM` always fit in `int`, with room to // spare. #define BN_MAX_WORDS (INT_MAX / (4 * BN_BITS2)) @@ -123,25 +123,25 @@ } // BN_num_bits_word returns the minimum number of bits needed to represent the -// value in |l|. +// value in `l`. unsigned BN_num_bits_word(BN_ULONG l) { - // |BN_num_bits| is often called on RSA prime factors. These have public bit + // `BN_num_bits` is often called on RSA prime factors. These have public bit // lengths, but all bits beyond the high bit are secret, so count bits in // constant time. BN_ULONG x, mask; int bits = (l != 0); #if BN_BITS2 > 32 - // Look at the upper half of |x|. |x| is at most 64 bits long. + // Look at the upper half of `x`. `x` is at most 64 bits long. x = l >> 32; - // Set |mask| to all ones if |x| (the top 32 bits of |l|) is non-zero and all + // Set `mask` to all ones if `x` (the top 32 bits of `l`) is non-zero and all // all zeros otherwise. mask = 0u - x; mask = (0u - (mask >> (BN_BITS2 - 1))); - // If |x| is non-zero, the lower half is included in the bit count in full, + // If `x` is non-zero, the lower half is included in the bit count in full, // and we count the upper half. Otherwise, we count the lower half. bits += 32 & mask; - l ^= (x ^ l) & mask; // |l| is |x| if |mask| and remains |l| otherwise. + l ^= (x ^ l) & mask; // `l` is `x` if `mask` and remains `l` otherwise. #endif // The remaining blocks are analogous iterations at lower powers of two. @@ -235,7 +235,7 @@ return 0; } OPENSSL_memmove(bn->d, words, num * sizeof(BN_ULONG)); - // |bn_wexpand| verified that |num| isn't too large. + // `bn_wexpand` verified that `num` isn't too large. bn->width = (int)num; bn->neg = 0; return 1; @@ -255,7 +255,7 @@ } int bssl::bn_fits_in_words(const BIGNUM *bn, size_t num) { - // All words beyond |num| must be zero. + // All words beyond `num` must be zero. BN_ULONG mask = 0; for (size_t i = num; i < (size_t)bn->width; i++) { mask |= bn->d[i];
diff --git a/crypto/fipsmodule/bn/bytes.cc.inc b/crypto/fipsmodule/bn/bytes.cc.inc index 4d3fada..ef2c87b 100644 --- a/crypto/fipsmodule/bn/bytes.cc.inc +++ b/crypto/fipsmodule/bn/bytes.cc.inc
@@ -24,8 +24,8 @@ void bssl::bn_big_endian_to_words(BN_ULONG *out, size_t out_len, const uint8_t *in, size_t in_len) { - // The caller should have sized |out| to fit |in| without truncating. This - // condition ensures we do not overflow |out|, so use a runtime check. + // The caller should have sized `out` to fit `in` without truncating. This + // condition ensures we do not overflow `out`, so use a runtime check. BSSL_CHECK(in_len <= out_len * sizeof(BN_ULONG)); // Load whole words. @@ -73,8 +73,8 @@ return nullptr; } - // |bn_wexpand| must check bounds on |num_words| to write it into - // |ret->dmax|. + // `bn_wexpand` must check bounds on `num_words` to write it into + // `ret->dmax`. assert(num_words <= INT_MAX); ret->width = (int)num_words; ret->neg = 0; @@ -99,7 +99,7 @@ return ret; } - // Reserve enough space in |ret|. + // Reserve enough space in `ret`. size_t num_words = ((len - 1) / BN_BYTES) + 1; if (!bn_wexpand(ret, num_words)) { BN_free(bn); @@ -121,8 +121,8 @@ return BN_lebin2bn(in, len, ret); } -// fits_in_bytes returns one if the |num_words| words in |words| can be -// represented in |num_bytes| bytes. +// fits_in_bytes returns one if the `num_words` words in `words` can be +// represented in `num_bytes` bytes. static int fits_in_bytes(const BN_ULONG *words, size_t num_words, size_t num_bytes) { const uint8_t *bytes = (const uint8_t *)words;
diff --git a/crypto/fipsmodule/bn/cmp.cc.inc b/crypto/fipsmodule/bn/cmp.cc.inc index aed2de1..c0a29ab 100644 --- a/crypto/fipsmodule/bn/cmp.cc.inc +++ b/crypto/fipsmodule/bn/cmp.cc.inc
@@ -38,7 +38,7 @@ constant_time_select_int(eq, ret, constant_time_select_int(lt, -1, 1)); } - // If |a| or |b| has non-zero words beyond |min|, they take precedence. + // If `a` or `b` has non-zero words beyond `min`, they take precedence. if (a_len < b_len) { crypto_word_t mask = 0; for (size_t i = a_len; i < b_len; i++) { @@ -72,7 +72,7 @@ } // We do not attempt to process the sign bit in constant time. Negative - // |BIGNUM|s should never occur in crypto, only calculators. + // `BIGNUM`s should never occur in crypto, only calculators. if (a->neg != b->neg) { if (a->neg) { return -1; @@ -143,7 +143,7 @@ int BN_equal_consttime(const BIGNUM *a, const BIGNUM *b) { BN_ULONG mask = 0; - // If |a| or |b| has more words than the other, all those words must be zero. + // If `a` or `b` has more words than the other, all those words must be zero. for (int i = a->width; i < b->width; i++) { mask |= b->d[i]; }
diff --git a/crypto/fipsmodule/bn/ctx.cc.inc b/crypto/fipsmodule/bn/ctx.cc.inc index 1d67281..a7381b0 100644 --- a/crypto/fipsmodule/bn/ctx.cc.inc +++ b/crypto/fipsmodule/bn/ctx.cc.inc
@@ -35,25 +35,25 @@ class BignumCtx : public bignum_ctx { public: ~BignumCtx() { - // All |BN_CTX_start| calls must be matched with |BN_CTX_end|, otherwise the + // All `BN_CTX_start` calls must be matched with `BN_CTX_end`, otherwise the // function may use more memory than expected, potentially without bound if - // done in a loop. Assert that all |BIGNUM|s have been released. + // done in a loop. Assert that all `BIGNUM`s have been released. assert(used_ == 0 || error_); } - // bignums_ is the stack of |BIGNUM|s managed by this |BN_CTX|. + // bignums_ is the stack of `BIGNUM`s managed by this `BN_CTX`. Vector<UniquePtr<BIGNUM>> bignums_; - // stack_ is the stack of |BN_CTX_start| frames. It is the value of |used_| at - // the time |BN_CTX_start| was called. + // stack_ is the stack of `BN_CTX_start` frames. It is the value of `used_` at + // the time `BN_CTX_start` was called. Vector<size_t> stack_; - // used_ is the number of |BIGNUM|s from |bignums_| that have been used. + // used_ is the number of `BIGNUM`s from `bignums_` that have been used. size_t used_ = 0; - // error_ is whether any operation on this |BN_CTX| failed. All subsequent + // error_ is whether any operation on this `BN_CTX` failed. All subsequent // operations will fail. bool error_ = false; - // defer_error_ is whether an operation on this |BN_CTX| has failed, but no + // defer_error_ is whether an operation on this `BN_CTX` has failed, but no // error has been pushed to the queue yet. This is used to defer errors from - // |BN_CTX_start| to |BN_CTX_get|. + // `BN_CTX_start` to `BN_CTX_get`. bool defer_error_ = false; }; @@ -71,14 +71,14 @@ auto *impl = FromOpaque(ctx); if (impl->error_) { - // Once an operation has failed, |impl->stack| no longer matches the number - // of |BN_CTX_end| calls to come. Do nothing. + // Once an operation has failed, `impl->stack` no longer matches the number + // of `BN_CTX_end` calls to come. Do nothing. return; } if (!impl->stack_.Push(impl->used_)) { impl->error_ = true; - // |BN_CTX_start| cannot fail, so defer the error to |BN_CTX_get|. + // `BN_CTX_start` cannot fail, so defer the error to `BN_CTX_get`. impl->defer_error_ = true; ERR_clear_error(); } @@ -107,7 +107,7 @@ BIGNUM *ret = impl->bignums_[impl->used_].get(); BN_zero(ret); - // This is bounded by |impl->bignums_.size()|, so it cannot overflow. + // This is bounded by `impl->bignums_.size()`, so it cannot overflow. impl->used_++; return ret; } @@ -116,8 +116,8 @@ auto *impl = FromOpaque(ctx); if (impl->error_) { - // Once an operation has failed, |impl->stack_| no longer matches the number - // of |BN_CTX_end| calls to come. Do nothing. + // Once an operation has failed, `impl->stack_` no longer matches the number + // of `BN_CTX_end` calls to come. Do nothing. return; }
diff --git a/crypto/fipsmodule/bn/div.cc.inc b/crypto/fipsmodule/bn/div.cc.inc index af522df..8147dcc 100644 --- a/crypto/fipsmodule/bn/div.cc.inc +++ b/crypto/fipsmodule/bn/div.cc.inc
@@ -35,8 +35,8 @@ using namespace bssl; -// bn_div_words divides a double-width |h|,|l| by |d| and returns the result, -// which must fit in a |BN_ULONG|, i.e. |h < d|. +// bn_div_words divides a double-width `h`,`l` by `d` and returns the result, +// which must fit in a `BN_ULONG`, i.e. `h < d`. [[maybe_unused]] static BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d) { assert(h < d); @@ -108,18 +108,18 @@ return ret; } -// bn_div_rem_words divides a double-width numerator (high half |nh| and low -// half |nl|) with a single-width divisor. It sets |*quotient_out| and -// |*rem_out| to be the quotient and numerator, respectively. The quotient must -// fit in a |BN_ULONG|, i.e. |nh < d|. +// bn_div_rem_words divides a double-width numerator (high half `nh` and low +// half `nl`) with a single-width divisor. It sets `*quotient_out` and +// `*rem_out` to be the quotient and numerator, respectively. The quotient must +// fit in a `BN_ULONG`, i.e. `nh < d`. static void bn_div_rem_words(BN_ULONG *quotient_out, BN_ULONG *rem_out, BN_ULONG nh, BN_ULONG nl, BN_ULONG d) { assert(nh < d); // This operation is the x86 and x86_64 DIV instruction, but it is difficult - // for the compiler to emit it. Dividing a |BN_ULLONG| by a |BN_ULONG| does - // not work because, a priori, the quotient may not fit in |BN_ULONG| and DIV + // for the compiler to emit it. Dividing a `BN_ULLONG` by a `BN_ULONG` does + // not work because, a priori, the quotient may not fit in `BN_ULONG` and DIV // will trap on overflow, not truncate. The compiler will instead emit a call - // to a more expensive support function (e.g. |__udivdi3|). Thus we use inline + // to a more expensive support function (e.g. `__udivdi3`). Thus we use inline // assembly or intrinsics to get the instruction. // // These is specific to x86 and x86_64; Arm and RISC-V do not have double-wide @@ -189,8 +189,8 @@ return 0; } - // This algorithm relies on |sdiv| being minimal width. We do not use this - // function on secret inputs, so leaking this is fine. Also minimize |snum| to + // This algorithm relies on `sdiv` being minimal width. We do not use this + // function on secret inputs, so leaking this is fine. Also minimize `snum` to // avoid looping on leading zeros, as we're not trying to be leak-free. bn_set_minimal_width(sdiv); bn_set_minimal_width(snum); @@ -199,10 +199,10 @@ d1 = (div_n == 1) ? 0 : sdiv->d[div_n - 2]; assert(d0 & (((BN_ULONG)1) << (BN_BITS2 - 1))); - // Extend |snum| with zeros to satisfy the long division invariants: - // - |snum| must have at least |div_n| + 1 words. - // - |snum|'s most significant word must be zero to guarantee the first loop - // iteration works with a prefix greater than |sdiv|. (This is the extra u0 + // Extend `snum` with zeros to satisfy the long division invariants: + // - `snum` must have at least `div_n` + 1 words. + // - `snum`'s most significant word must be zero to guarantee the first loop + // iteration works with a prefix greater than `sdiv`. (This is the extra u0 // digit in Knuth step D1.) num_n = snum->width <= div_n ? div_n + 1 : snum->width + 1; if (!bn_resize_words(snum, num_n)) { @@ -356,18 +356,18 @@ BN_ULONG bssl::bn_reduce_once(BN_ULONG *r, const BN_ULONG *a, BN_ULONG carry, const BN_ULONG *m, size_t num) { assert(r != a); - // |r| = |a| - |m|. |bn_sub_words| performs the bulk of the subtraction, and - // then we apply the borrow to |carry|. + // `r` = `a` - `m`. `bn_sub_words` performs the bulk of the subtraction, and + // then we apply the borrow to `carry`. carry -= bn_sub_words(r, a, m, num); - // We know 0 <= |a| < 2*|m|, so -|m| <= |r| < |m|. + // We know 0 <= `a` < 2*`m`, so -`m` <= `r` < `m`. // - // If 0 <= |r| < |m|, |r| fits in |num| words and |carry| is zero. We then - // wish to select |r| as the answer. Otherwise -m <= r < 0 and we wish to - // return |r| + |m|, or |a|. |carry| must then be -1 or all ones. In both - // cases, |carry| is a suitable input to |bn_select_words|. + // If 0 <= `r` < `m`, `r` fits in `num` words and `carry` is zero. We then + // wish to select `r` as the answer. Otherwise -m <= r < 0 and we wish to + // return `r` + `m`, or `a`. `carry` must then be -1 or all ones. In both + // cases, `carry` is a suitable input to `bn_select_words`. // - // Although |carry| may be one if it was one on input and |bn_sub_words| - // returns zero, this would give |r| > |m|, violating our input assumptions. + // Although `carry` may be one if it was one on input and `bn_sub_words` + // returns zero, this would give `r` > `m`, violating our input assumptions. declassify_assert(carry + 1 <= 1); bn_select_words(r, carry, a /* r < 0 */, r /* r >= 0 */, num); return carry; @@ -376,7 +376,7 @@ BN_ULONG bssl::bn_reduce_once_in_place(BN_ULONG *r, BN_ULONG carry, const BN_ULONG *m, BN_ULONG *tmp, size_t num) { - // See |bn_reduce_once| for why this logic works. + // See `bn_reduce_once` for why this logic works. carry -= bn_sub_words(tmp, r, m, num); declassify_assert(carry + 1 <= 1); bn_select_words(r, carry, r /* tmp < 0 */, tmp /* tmp >= 0 */, num); @@ -438,14 +438,14 @@ r->width = divisor->width; r->neg = 0; - // Incorporate |numerator| into |r|, one bit at a time, reducing after each - // step. We maintain the invariant that |0 <= r < divisor| and - // |q * divisor + r = n| where |n| is the portion of |numerator| incorporated + // Incorporate `numerator` into `r`, one bit at a time, reducing after each + // step. We maintain the invariant that `0 <= r < divisor` and + // `q * divisor + r = n` where `n` is the portion of `numerator` incorporated // so far. // - // First, we short-circuit the loop: if we know |divisor| has at least - // |divisor_min_bits| bits, the top |divisor_min_bits - 1| can be incorporated - // without reductions. This significantly speeds up |RSA_check_key|. For + // First, we short-circuit the loop: if we know `divisor` has at least + // `divisor_min_bits` bits, the top `divisor_min_bits - 1` can be incorporated + // without reductions. This significantly speeds up `RSA_check_key`. For // simplicity, we round down to a whole number of words. declassify_assert(divisor_min_bits <= BN_num_bits(divisor)); initial_words = 0; @@ -462,13 +462,13 @@ for (int bit = BN_BITS2 - 1; bit >= 0; bit--) { // Incorporate the next bit of the numerator, by computing // r = 2*r or 2*r + 1. Note the result fits in one more word. We store the - // extra word in |carry|. + // extra word in `carry`. BN_ULONG carry = bn_add_words(r->d, r->d, r->d, divisor->width); r->d[0] |= (numerator->d[i] >> bit) & 1; - // |r| was previously fully-reduced, so we know: + // `r` was previously fully-reduced, so we know: // 2*0 <= r <= 2*(divisor-1) + 1 // 0 <= r <= 2*divisor - 1 < 2*divisor. - // Thus |r| satisfies the preconditions for |bn_reduce_once_in_place|. + // Thus `r` satisfies the preconditions for `bn_reduce_once_in_place`. BN_ULONG subtracted = bn_reduce_once_in_place(r->d, carry, divisor->d, tmp->d, divisor->width); // The corresponding bit of the quotient is set iff we needed to subtract. @@ -494,11 +494,11 @@ return ret; } -// bn_resized_from_ctx returns |bn| with width at least |width| or NULL on +// bn_resized_from_ctx returns `bn` with width at least `width` or NULL on // error. This is so it may be used with low-level "words" functions. If -// necessary, it allocates a new |BIGNUM| with a lifetime of the current scope -// in |ctx|, so the caller does not need to explicitly free it. |bn| must fit in -// |width| words. +// necessary, it allocates a new `BIGNUM` with a lifetime of the current scope +// in `ctx`, so the caller does not need to explicitly free it. `bn` must fit in +// `width` words. static const BIGNUM *bn_resized_from_ctx(const BIGNUM *bn, size_t width, BN_CTX *ctx) { if ((size_t)bn->width >= width) { @@ -679,7 +679,7 @@ return 0; } - // normalize input for |bn_div_rem_words|. + // normalize input for `bn_div_rem_words`. j = BN_BITS2 - BN_num_bits_word(w); w <<= j; if (!BN_lshift(a, a, j)) { @@ -713,8 +713,8 @@ } #ifndef BN_CAN_DIVIDE_ULLONG - // If |w| is too long and we don't have |BN_ULLONG| division then we need to - // fall back to using |BN_div_word|. + // If `w` is too long and we don't have `BN_ULLONG` division then we need to + // fall back to using `BN_div_word`. if (w > ((BN_ULONG)1 << BN_BITS4)) { BIGNUM *tmp = BN_dup(a); if (tmp == nullptr) {
diff --git a/crypto/fipsmodule/bn/div_extra.cc.inc b/crypto/fipsmodule/bn/div_extra.cc.inc index 52e1be6..b518b4e 100644 --- a/crypto/fipsmodule/bn/div_extra.cc.inc +++ b/crypto/fipsmodule/bn/div_extra.cc.inc
@@ -26,13 +26,13 @@ // http://ridiculousfish.com/blog/posts/labor-of-division-episode-i.html // // We use 32-bit numerator and 16-bit divisor for simplicity. This allows -// computing |m| and |q| without architecture-specific code. +// computing `m` and `q` without architecture-specific code. -// mod_u16 returns |n| mod |d|. |p| and |m| are the "magic numbers" for |d| (see +// mod_u16 returns `n` mod `d`. `p` and `m` are the "magic numbers" for `d` (see // reference). For proof of correctness in Coq, see // https://github.com/davidben/fiat-crypto/blob/barrett/src/Arithmetic/BarrettReduction/RidiculousFish.v -// Note the Coq version of |mod_u16| additionally includes the computation of -// |p| and |m| from |bn_mod_u16_consttime| below. +// Note the Coq version of `mod_u16` additionally includes the computation of +// `p` and `m` from `bn_mod_u16_consttime` below. static uint16_t mod_u16(uint32_t n, uint16_t d, uint32_t p, uint32_t m) { // Compute floor(n/d) per steps 3 through 5. uint32_t q = ((uint64_t)m * n) >> 32; @@ -46,11 +46,11 @@ return n; } -// shift_and_add_mod_u16 returns |r| * 2^32 + |a| mod |d|. |p| and |m| are the -// "magic numbers" for |d| (see reference). +// shift_and_add_mod_u16 returns `r` * 2^32 + `a` mod `d`. `p` and `m` are the +// "magic numbers" for `d` (see reference). static uint16_t shift_and_add_mod_u16(uint16_t r, uint32_t a, uint16_t d, uint32_t p, uint32_t m) { - // Incorporate |a| in two 16-bit chunks. + // Incorporate `a` in two 16-bit chunks. uint32_t t = r; t <<= 16; t |= a >> 16; @@ -67,11 +67,11 @@ return 0; } - // Compute the "magic numbers" for |d|. See steps 1 and 2. + // Compute the "magic numbers" for `d`. See steps 1 and 2. // This computes p = ceil(log_2(d)). uint32_t p = BN_num_bits_word(d - 1); - // This operation is not constant-time, but |p| and |d| are public values. - // Note that |p| is at most 16, so the computation fits in |uint64_t|. + // This operation is not constant-time, but `p` and `d` are public values. + // Note that `p` is at most 16, so the computation fits in `uint64_t`. assert(p <= 16); uint32_t m = (uint32_t)(((UINT64_C(1) << (32 + p)) + d - 1) / d);
diff --git a/crypto/fipsmodule/bn/exponentiation.cc.inc b/crypto/fipsmodule/bn/exponentiation.cc.inc index 869c78e..911ac43 100644 --- a/crypto/fipsmodule/bn/exponentiation.cc.inc +++ b/crypto/fipsmodule/bn/exponentiation.cc.inc
@@ -30,11 +30,11 @@ #if defined(OPENSSL_BN_ASM_MONT5) -// bn_mul_mont_gather5 multiples loads index |power| of |table|, multiplies it -// by |ap| modulo |np|, and stores the result in |rp|. The values are |num| -// words long and represented in Montgomery form. |n0| is a pointer to the -// corresponding field in |BN_MONT_CTX|. |table| must be aligned to at least -// 16 bytes. |power| must be less than 32 and is treated as secret. +// bn_mul_mont_gather5 multiples loads index `power` of `table`, multiplies it +// by `ap` modulo `np`, and stores the result in `rp`. The values are `num` +// words long and represented in Montgomery form. `n0` is a pointer to the +// corresponding field in `BN_MONT_CTX`. `table` must be aligned to at least +// 16 bytes. `power` must be less than 32 and is treated as secret. // // WARNING: This function implements Almost Montgomery Multiplication from // https://eprint.iacr.org/2011/239. The inputs do not need to be fully reduced. @@ -51,11 +51,11 @@ } } -// bn_power5 squares |ap| five times and multiplies it by the value stored at -// index |power| of |table|, modulo |np|. It stores the result in |rp|. The -// values are |num| words long and represented in Montgomery form. |n0| is a -// pointer to the corresponding field in |BN_MONT_CTX|. |num| must be divisible -// by 8. |power| must be less than 32 and is treated as secret. +// bn_power5 squares `ap` five times and multiplies it by the value stored at +// index `power` of `table`, modulo `np`. It stores the result in `rp`. The +// values are `num` words long and represented in Montgomery form. `n0` is a +// pointer to the corresponding field in `BN_MONT_CTX`. `num` must be divisible +// by 8. `power` must be less than 32 and is treated as secret. // // WARNING: This function implements Almost Montgomery Multiplication from // https://eprint.iacr.org/2011/239. The inputs do not need to be fully reduced. @@ -74,7 +74,7 @@ #endif // defined(OPENSSL_BN_ASM_MONT5) // BN_window_bits_for_exponent_size returns sliding window size for mod_exp with -// a |b| bit exponent. +// a `b` bit exponent. // // For window size 'w' (w >= 2) and a random 'b' bits exponent, the number of // multiplications is a constant plus on average @@ -114,16 +114,16 @@ // TABLE_SIZE is the maximum precomputation table size for *variable* sliding // windows. This must be 2^(max_window - 1), where max_window is the largest -// value returned from |BN_window_bits_for_exponent_size|. +// value returned from `BN_window_bits_for_exponent_size`. #define TABLE_SIZE 32 // TABLE_BITS_SMALL is the smallest value returned from -// |BN_window_bits_for_exponent_size| when |b| is at most |BN_BITS2| * -// |BN_SMALL_MAX_WORDS| words. +// `BN_window_bits_for_exponent_size` when `b` is at most `BN_BITS2` * +// `BN_SMALL_MAX_WORDS` words. #define TABLE_BITS_SMALL 5 -// TABLE_SIZE_SMALL is the same as |TABLE_SIZE|, but when |b| is at most -// |BN_BITS2| * |BN_SMALL_MAX_WORDS|. +// TABLE_SIZE_SMALL is the same as `TABLE_SIZE`, but when `b` is at most +// `BN_BITS2` * `BN_SMALL_MAX_WORDS`. #define TABLE_SIZE_SMALL (1 << (TABLE_BITS_SMALL - 1)) int BN_mod_exp_mont(BIGNUM *rr, const BIGNUM *a, const BIGNUM *p, @@ -136,7 +136,7 @@ OPENSSL_PUT_ERROR(BN, BN_R_NEGATIVE_NUMBER); return 0; } - // |a| is secret, but |a < m| is not. + // `a` is secret, but `a < m` is not. if (a->neg || constant_time_declassify_int(BN_ucmp(a, m)) >= 0) { OPENSSL_PUT_ERROR(BN, BN_R_INPUT_NOT_REDUCED); return 0; @@ -172,7 +172,7 @@ } // We exponentiate by looking at sliding windows of the exponent and - // precomputing powers of |a|. Windows may be shifted so they always end on a + // precomputing powers of `a`. Windows may be shifted so they always end on a // set bit, so only precompute odd powers. We compute val[i] = a^(2*i + 1) // for i = 0 to 2^(window-1), all in Montgomery form. int window = BN_window_bits_for_exponent_size(bits); @@ -193,8 +193,8 @@ } } - // |p| is non-zero, so at least one window is non-zero. To save some - // multiplications, defer initializing |r| until then. + // `p` is non-zero, so at least one window is non-zero. To save some + // multiplications, defer initializing `r` until then. int r_is_one = 1; int wstart = bits - 1; // The top bit of the window. for (;;) { @@ -220,7 +220,7 @@ } } - // Shift |r| to the end of the window. + // Shift `r` to the end of the window. if (!r_is_one) { for (int i = 0; i < wsize + 1; i++) { if (!BN_mod_mul_montgomery(r, r, r, mont, ctx)) { @@ -246,7 +246,7 @@ wstart -= wsize + 1; } - // |p| is non-zero, so |r_is_one| must be cleared at some point. + // `p` is non-zero, so `r_is_one` must be cleared at some point. assert(!r_is_one); return BN_from_montgomery(rr, r, mont, ctx); @@ -261,8 +261,8 @@ } assert(BN_is_odd(&mont->N)); - // Count the number of bits in |p|, skipping leading zeros. Note this function - // treats |p| as public. + // Count the number of bits in `p`, skipping leading zeros. Note this function + // treats `p` as public. while (num_p != 0 && p[num_p - 1] == 0) { num_p--; } @@ -274,12 +274,12 @@ assert(bits != 0); // We exponentiate by looking at sliding windows of the exponent and - // precomputing powers of |a|. Windows may be shifted so they always end on a + // precomputing powers of `a`. Windows may be shifted so they always end on a // set bit, so only precompute odd powers. We compute val[i] = a^(2*i + 1) for // i = 0 to 2^(window-1), all in Montgomery form. unsigned window = BN_window_bits_for_exponent_size(bits); if (window > TABLE_BITS_SMALL) { - window = TABLE_BITS_SMALL; // Tolerate excessively large |p|. + window = TABLE_BITS_SMALL; // Tolerate excessively large `p`. } BN_ULONG val[TABLE_SIZE_SMALL][BN_SMALL_MAX_WORDS]; OPENSSL_memcpy(val[0], a, num * sizeof(BN_ULONG)); @@ -291,8 +291,8 @@ } } - // |p| is non-zero, so at least one window is non-zero. To save some - // multiplications, defer initializing |r| until then. + // `p` is non-zero, so at least one window is non-zero. To save some + // multiplications, defer initializing `r` until then. int r_is_one = 1; size_t wstart = bits - 1; // The top bit of the window. for (;;) { @@ -318,7 +318,7 @@ } } - // Shift |r| to the end of the window. + // Shift `r` to the end of the window. if (!r_is_one) { for (unsigned i = 0; i < wsize + 1; i++) { bn_mod_mul_montgomery_small(r, r, r, num, mont); @@ -339,7 +339,7 @@ wstart -= wsize + 1; } - // |p| is non-zero, so |r_is_one| must be cleared at some point. + // `p` is non-zero, so `r_is_one` must be cleared at some point. assert(!r_is_one); OPENSSL_cleanse(val, sizeof(val)); } @@ -372,7 +372,7 @@ static void copy_to_prebuf(const BIGNUM *b, int top, BN_ULONG *table, int idx, int window) { int ret = bn_copy_words(table + idx * top, top, b); - assert(ret); // |b| is guaranteed to fit. + assert(ret); // `b` is guaranteed to fit. (void)ret; } @@ -385,9 +385,9 @@ OPENSSL_memset(b->d, 0, sizeof(BN_ULONG) * top); const int width = 1 << window; for (int i = 0; i < width; i++, table += top) { - // Use a value barrier to prevent Clang from adding a branch when |i != idx| + // Use a value barrier to prevent Clang from adding a branch when `i != idx` // and making this copy not constant time. Clang is still allowed to learn - // that |mask| is constant across the inner loop, so this won't inhibit any + // that `mask` is constant across the inner loop, so this won't inhibit any // vectorization it might do. BN_ULONG mask = value_barrier_w(constant_time_eq_int(i, idx)); for (int j = 0; j < top; j++) { @@ -409,7 +409,7 @@ ((b) > 937 ? 6 : (b) > 306 ? 5 : (b) > 89 ? 4 : (b) > 22 ? 3 : 1) #define BN_MAX_MOD_EXP_CTIME_WINDOW (6) -// This variant of |BN_mod_exp_mont| uses fixed windows and fixed memory access +// This variant of `BN_mod_exp_mont` uses fixed windows and fixed memory access // patterns to protect secret exponents (cf. the hyper-threading timing attacks // pointed out by Colin Percival, // http://www.daemonology.net/hyperthreading-considered-harmful/) @@ -430,14 +430,14 @@ OPENSSL_PUT_ERROR(BN, BN_R_NEGATIVE_NUMBER); return 0; } - // |a| is secret, but it is required to be in range, so these comparisons may + // `a` is secret, but it is required to be in range, so these comparisons may // be leaked. if (a->neg || constant_time_declassify_int(BN_ucmp(a, m) >= 0)) { OPENSSL_PUT_ERROR(BN, BN_R_INPUT_NOT_REDUCED); return 0; } - // Use all bits stored in |p|, rather than |BN_num_bits|, so we do not leak + // Use all bits stored in `p`, rather than `BN_num_bits`, so we do not leak // whether the top bits are zero. int max_bits = p->width * BN_BITS2; int bits = max_bits; @@ -461,8 +461,8 @@ mont = new_mont.get(); } - // Use the width in |mont->N|, rather than the copy in |m|. The assembly - // implementation assumes it can use |top| to size R. + // Use the width in `mont->N`, rather than the copy in `m`. The assembly + // implementation assumes it can use `top` to size R. top = mont->N.width; #if defined(OPENSSL_BN_ASM_MONT5) || defined(RSAZ_ENABLED) @@ -494,7 +494,7 @@ window = BN_window_bits_for_ctime_exponent_size(bits); assert(window <= BN_MAX_MOD_EXP_CTIME_WINDOW); - // Calculating |powerbuf_len| below cannot overflow because of the bound on + // Calculating `powerbuf_len` below cannot overflow because of the bound on // Montgomery reduction. assert((size_t)top <= BN_MONTGOMERY_MAX_WORDS); static_assert( @@ -505,13 +505,13 @@ #if defined(OPENSSL_BN_ASM_MONT5) if (window >= 5) { window = 5; // ~5% improvement for RSA2048 sign, and even for RSA4096 - // Reserve space for the |mont->N| copy. + // Reserve space for the `mont->N` copy. powerbuf_len += top * sizeof(mont->N.d[0]); } #endif // Allocate a buffer large enough to hold all of the pre-computed - // powers of |am|, |am| itself, and |tmp|. + // powers of `am`, `am` itself, and `tmp`. num_powers = 1 << window; powerbuf_len += sizeof(m->d[0]) * top * (num_powers + 2); @@ -519,7 +519,7 @@ if (powerbuf_len <= sizeof(storage)) { powerbuf = storage; } - // |storage| is more than large enough to handle 1024-bit inputs. + // `storage` is more than large enough to handle 1024-bit inputs. assert(powerbuf != nullptr || top * BN_BITS2 > 1024); #endif if (powerbuf == nullptr) { @@ -532,7 +532,7 @@ } OPENSSL_memset(powerbuf, 0, powerbuf_len); - // Place |tmp| and |am| right after powers table. + // Place `tmp` and `am` right after powers table. BIGNUM tmp, am; tmp.d = powerbuf + top * num_powers; am.d = tmp.d + top; @@ -561,24 +561,24 @@ // exponentiation, used in RSA-1024 with CRT, but RSA-1024 is no longer // important. // - // |bn_mul_mont_gather5| and |bn_power5| implement the "almost" reduction + // `bn_mul_mont_gather5` and `bn_power5` implement the "almost" reduction // variant, so the values here may not be fully reduced. They are bounded by R - // (i.e. they fit in |top| words), not |m|. Additionally, we pass these - // "almost" reduced inputs into |bn_mul_mont_words|, which implements the - // normal reduction variant. Given those inputs, |bn_mul_mont_words| may not + // (i.e. they fit in `top` words), not `m`. Additionally, we pass these + // "almost" reduced inputs into `bn_mul_mont_words`, which implements the + // normal reduction variant. Given those inputs, `bn_mul_mont_words` may not // give reduced output, but it will still produce "almost" reduced output. // // TODO(davidben): Using "almost" reduction complicates analysis of this code, // and its interaction with other parts of the project. Determine whether this // is actually necessary for performance. if (window == 5 && top > 1) { - // Copy |mont->N| to improve cache locality. + // Copy `mont->N` to improve cache locality. BN_ULONG *np = am.d + top; for (i = 0; i < top; i++) { np[i] = mont->N.d[i]; } - // Fill |powerbuf| with the first 32 powers of |am|. + // Fill `powerbuf` with the first 32 powers of `am`. const BN_ULONG *n0 = mont->n0; bn_scatter5(tmp.d, top, powerbuf, 0); bn_scatter5(am.d, am.width, powerbuf, 1); @@ -590,7 +590,7 @@ bn_mul_mont_words(tmp.d, tmp.d, tmp.d, np, n0, top); bn_scatter5(tmp.d, top, powerbuf, i); } - // Compute odd powers |i| based on |i - 1|, then all powers |i * 2^j|. + // Compute odd powers `i` based on `i - 1`, then all powers `i * 2^j`. for (i = 3; i < 32; i += 2) { bn_mul_mont_gather5(tmp.d, am.d, powerbuf, np, n0, top, i - 1); bn_scatter5(tmp.d, top, powerbuf, i); @@ -606,7 +606,7 @@ } bn_gather5(tmp.d, top, powerbuf, wvalue); - // At this point |bits| is 4 mod 5 and at least -1. (|bits| is the first bit + // At this point `bits` is 4 mod 5 and at least -1. (`bits` is the first bit // that has not been read yet.) assert(bits >= -1 && (bits == -1 || bits % 5 == 4)); @@ -628,16 +628,16 @@ } else { const uint8_t *p_bytes = (const uint8_t *)p->d; assert(bits < max_bits); - // |p = 0| has been handled as a special case, so |max_bits| is at least + // `p = 0` has been handled as a special case, so `max_bits` is at least // one word. assert(max_bits >= 64); // If the first bit to be read lands in the last byte, unroll the first - // iteration to avoid reading past the bounds of |p->d|. (After the first - // iteration, we are guaranteed to be past the last byte.) Note |bits| + // iteration to avoid reading past the bounds of `p->d`. (After the first + // iteration, we are guaranteed to be past the last byte.) Note `bits` // here is the top bit, inclusive. if (bits - 4 >= max_bits - 8) { - // Read five bits from |bits-4| through |bits|, inclusive. + // Read five bits from `bits-4` through `bits`, inclusive. wvalue = p_bytes[p->width * BN_BYTES - 1]; wvalue >>= (bits - 4) & 7; wvalue &= 0x1f; @@ -645,7 +645,7 @@ bn_power5(tmp.d, tmp.d, powerbuf, np, n0, top, wvalue); } while (bits >= 0) { - // Read five bits from |bits-4| through |bits|, inclusive. + // Read five bits from `bits-4` through `bits`, inclusive. int first_bit = bits - 4; uint16_t val; OPENSSL_memcpy(&val, p_bytes + (first_bit >> 3), sizeof(val)); @@ -655,8 +655,8 @@ bn_power5(tmp.d, tmp.d, powerbuf, np, n0, top, val); } } - // The result is now in |tmp| in Montgomery form, but it may not be fully - // reduced. This is within bounds for |BN_from_montgomery| (tmp < R <= m*R) + // The result is now in `tmp` in Montgomery form, but it may not be fully + // reduced. This is within bounds for `BN_from_montgomery` (tmp < R <= m*R) // so it will, when converting from Montgomery form, produce a fully reduced // result. // @@ -725,9 +725,9 @@ } // Convert the final result from Montgomery to standard format. If we used the - // |OPENSSL_BN_ASM_MONT5| codepath, |tmp| may not be fully reduced. It is only - // bounded by R rather than |m|. However, that is still within bounds for - // |BN_from_montgomery|, which implements full Montgomery reduction, not + // `OPENSSL_BN_ASM_MONT5` codepath, `tmp` may not be fully reduced. It is only + // bounded by R rather than `m`. However, that is still within bounds for + // `BN_from_montgomery`, which implements full Montgomery reduction, not // "almost" Montgomery reduction. if (!BN_from_montgomery(rr, &tmp, mont, ctx)) { goto err;
diff --git a/crypto/fipsmodule/bn/gcd.cc.inc b/crypto/fipsmodule/bn/gcd.cc.inc index 4fdb2e9..d78185c 100644 --- a/crypto/fipsmodule/bn/gcd.cc.inc +++ b/crypto/fipsmodule/bn/gcd.cc.inc
@@ -211,7 +211,7 @@ return nullptr; } - new_out.release(); // Passed to the caller via |out|. + new_out.release(); // Passed to the caller via `out`. return out; } @@ -219,7 +219,7 @@ const BN_MONT_CTX *mont, BN_CTX *ctx) { *out_no_inverse = 0; - // |a| is secret, but it is required to be in range, so these comparisons may + // `a` is secret, but it is required to be in range, so these comparisons may // be leaked. if (BN_is_negative(a) || constant_time_declassify_int(BN_cmp(a, &mont->N) >= 0)) { @@ -232,15 +232,15 @@ return 0; } - // |BN_mod_inverse_odd| is leaky, so generate a secret blinding factor and - // blind |a|. This works because (ar)^-1 * r = a^-1, supposing r is + // `BN_mod_inverse_odd` is leaky, so generate a secret blinding factor and + // blind `a`. This works because (ar)^-1 * r = a^-1, supposing r is // invertible. If r is not invertible, this function will fail. However, we // only use this in RSA, where stumbling on an uninvertible element means // stumbling on the key's factorization. That is, if this function fails, the // RSA key was not actually a product of two large primes. // // TODO(crbug.com/boringssl/677): When the PRNG output is marked secret by - // default, the explicit |bn_secret| call can be removed. + // default, the explicit `bn_secret` call can be removed. if (!BN_rand_range_ex(blinding_factor.get(), 1, &mont->N)) { return 0; } @@ -249,8 +249,8 @@ return 0; } - // Once blinded, |out| is no longer secret, so it may be passed to a leaky - // mod inverse function. Note |blinding_factor| is secret, so |out| will be + // Once blinded, `out` is no longer secret, so it may be passed to a leaky + // mod inverse function. Note `blinding_factor` is secret, so `out` will be // secret again after multiplying. bn_declassify(out); if (!BN_mod_inverse_odd(out, out_no_inverse, out, &mont->N, ctx) ||
diff --git a/crypto/fipsmodule/bn/gcd_extra.cc.inc b/crypto/fipsmodule/bn/gcd_extra.cc.inc index a48762f..867147d 100644 --- a/crypto/fipsmodule/bn/gcd_extra.cc.inc +++ b/crypto/fipsmodule/bn/gcd_extra.cc.inc
@@ -72,7 +72,7 @@ return 0; } - // Each loop iteration halves at least one of |u| and |v|. Thus we need at + // Each loop iteration halves at least one of `u` and `v`. Thus we need at // most the combined bit width of inputs for at least one value to be zero. x_bits = x->width * BN_BITS2; y_bits = y->width * BN_BITS2; @@ -86,14 +86,14 @@ for (unsigned i = 0; i < num_iters; i++) { BN_ULONG both_odd = word_is_odd_mask(u->d[0]) & word_is_odd_mask(v->d[0]); - // If both |u| and |v| are odd, subtract the smaller from the larger. + // If both `u` and `v` are odd, subtract the smaller from the larger. BN_ULONG u_less_than_v = (BN_ULONG)0 - bn_sub_words(tmp->d, u->d, v->d, width); bn_select_words(u->d, both_odd & ~u_less_than_v, tmp->d, u->d, width); bn_sub_words(tmp->d, v->d, u->d, width); bn_select_words(v->d, both_odd & u_less_than_v, tmp->d, v->d, width); - // At least one of |u| and |v| is now even. + // At least one of `u` and `v` is now even. BN_ULONG u_is_odd = word_is_odd_mask(u->d[0]); BN_ULONG v_is_odd = word_is_odd_mask(v->d[0]); declassify_assert(!(u_is_odd & v_is_odd)); @@ -106,8 +106,8 @@ maybe_rshift1_words(v->d, ~v_is_odd, tmp->d, width); } - // One of |u| or |v| is zero at this point. The algorithm usually makes |u| - // zero, unless |y| was already zero on input. Fix this by combining the + // One of `u` or `v` is zero at this point. The algorithm usually makes `u` + // zero, unless `y` was already zero on input. Fix this by combining the // values. declassify_assert(BN_is_zero(u) | BN_is_zero(v)); for (size_t i = 0; i < width; i++) { @@ -132,7 +132,7 @@ return 0; } - // Check that 2^|shift| * |gcd| is one. + // Check that 2^`shift` * `gcd` is one. if (gcd->width == 0) { *out_relatively_prime = 0; } else { @@ -154,7 +154,7 @@ return gcd != nullptr && // bn_mul_consttime(r, a, b, ctx) && bn_gcd_consttime(gcd, &shift, a, b, ctx) && - // |gcd| has a secret bit width. + // `gcd` has a secret bit width. bn_div_consttime(r, nullptr, r, gcd, /*divisor_min_bits=*/0, ctx) && bn_rshift_secret_shift(r, r, shift, ctx); } @@ -183,9 +183,9 @@ // negative numbers. // // For more details and proof of correctness, see - // https://github.com/mit-plv/fiat-crypto/pull/333. In particular, see |step| - // and |mod_inverse_consttime| for the algorithm in Gallina and see - // |mod_inverse_consttime_spec| for the correctness result. + // https://github.com/mit-plv/fiat-crypto/pull/333. In particular, see `step` + // and `mod_inverse_consttime` for the algorithm in Gallina and see + // `mod_inverse_consttime_spec` for the correctness result. if (!BN_is_odd(a) && !BN_is_odd(n)) { *out_no_inverse = 1; @@ -193,8 +193,8 @@ return 0; } - // This function exists to compute the RSA private exponent, where |a| is one - // word. We'll thus use |a_width| when available. + // This function exists to compute the RSA private exponent, where `a` is one + // word. We'll thus use `a_width` when available. size_t n_width = n->width, a_width = a->width; if (a_width > n_width) { a_width = n_width; @@ -222,25 +222,25 @@ !BN_copy(v, n) || // !BN_one(A) || // !BN_one(D) || - // For convenience, size |u| and |v| equivalently. + // For convenience, size `u` and `v` equivalently. !bn_resize_words(u, n_width) || // !bn_resize_words(v, n_width) || - // |A| and |C| are bounded by |m|. + // `A` and `C` are bounded by `m`. !bn_resize_words(A, n_width) || // !bn_resize_words(C, n_width) || - // |B| and |D| are bounded by |a|. + // `B` and `D` are bounded by `a`. !bn_resize_words(B, a_width) || // !bn_resize_words(D, a_width) || - // |tmp| and |tmp2| may be used at either size. + // `tmp` and `tmp2` may be used at either size. !bn_resize_words(tmp, n_width) || // !bn_resize_words(tmp2, n_width)) { return 0; } - // Each loop iteration halves at least one of |u| and |v|. Thus we need at + // Each loop iteration halves at least one of `u` and `v`. Thus we need at // most the combined bit width of inputs for at least one value to be zero. - // |a_bits| and |n_bits| cannot overflow because |bn_wexpand| ensures bit - // counts fit in even |int|. + // `a_bits` and `n_bits` cannot overflow because `bn_wexpand` ensures bit + // counts fit in even `int`. a_bits = a_width * BN_BITS2; n_bits = n_width * BN_BITS2; num_iters = a_bits + n_bits; @@ -265,7 +265,7 @@ for (size_t i = 0; i < num_iters; i++) { BN_ULONG both_odd = word_is_odd_mask(u->d[0]) & word_is_odd_mask(v->d[0]); - // If both |u| and |v| are odd, subtract the smaller from the larger. + // If both `u` and `v` are odd, subtract the smaller from the larger. BN_ULONG v_less_than_u = (BN_ULONG)0 - bn_sub_words(tmp->d, v->d, u->d, n_width); bn_select_words(v->d, both_odd & ~v_less_than_u, tmp->d, v->d, n_width); @@ -285,8 +285,8 @@ bn_select_words(B->d, both_odd & v_less_than_u, tmp->d, B->d, a_width); bn_select_words(D->d, both_odd & ~v_less_than_u, tmp->d, D->d, a_width); - // Our loop invariants hold at this point. Additionally, exactly one of |u| - // and |v| is now even. + // Our loop invariants hold at this point. Additionally, exactly one of `u` + // and `v` is now even. BN_ULONG u_is_even = ~word_is_odd_mask(u->d[0]); BN_ULONG v_is_even = ~word_is_odd_mask(v->d[0]); declassify_assert(u_is_even != v_is_even);
diff --git a/crypto/fipsmodule/bn/montgomery.cc.inc b/crypto/fipsmodule/bn/montgomery.cc.inc index 4bc6247..4be4ecf 100644 --- a/crypto/fipsmodule/bn/montgomery.cc.inc +++ b/crypto/fipsmodule/bn/montgomery.cc.inc
@@ -95,7 +95,7 @@ OPENSSL_PUT_ERROR(BN, ERR_R_INTERNAL_ERROR); return 0; } - // |mont->N| is always stored minimally. Computing RR efficiently leaks the + // `mont->N` is always stored minimally. Computing RR efficiently leaks the // size of the modulus. While the modulus may be private in RSA (one of the // primes), their sizes are public, so this is fine. bn_set_minimal_width(&mont->N); @@ -103,8 +103,8 @@ // Find n0 such that n0 * N == -1 (mod r). // // Only certain BN_BITS2<=32 platforms actually make use of n0[1]. For the - // others, we could use a shorter R value and use faster |BN_ULONG|-based - // math instead of |uint64_t|-based math, which would be double-precision. + // others, we could use a shorter R value and use faster `BN_ULONG`-based + // math instead of `uint64_t`-based math, which would be double-precision. // However, currently only the assembler files know which is which. static_assert(BN_MONT_CTX_N0_LIMBS == 1 || BN_MONT_CTX_N0_LIMBS == 2, "BN_MONT_CTX_N0_LIMBS value is invalid"); @@ -134,9 +134,9 @@ // Save RR = R**2 (mod N). R is the smallest power of 2**BN_BITS2 such that R // > mod. Even though the assembly on some 32-bit platforms works with 64-bit - // values, using |BN_BITS2| here, rather than |BN_MONT_CTX_N0_LIMBS * - // BN_BITS2|, is correct because R**2 will still be a multiple of the latter - // as |BN_MONT_CTX_N0_LIMBS| is either one or two. + // values, using `BN_BITS2` here, rather than + // `BN_MONT_CTX_N0_LIMBS * BN_BITS2`, is correct because R**2 will still be a + // multiple of the latter as `BN_MONT_CTX_N0_LIMBS` is either one or two. unsigned lgBigR = mont->N.width * BN_BITS2; BN_zero(&mont->RR); int ok = BN_set_bit(&mont->RR, lgBigR * 2) && @@ -196,9 +196,9 @@ return 0; } - // Add multiples of |n| to |r| until R = 2^(nl * BN_BITS2) divides it. On - // input, we had |r| < |n| * R, so now |r| < 2 * |n| * R. Note that |r| - // includes |carry| which is stored separately. + // Add multiples of `n` to `r` until R = 2^(nl * BN_BITS2) divides it. On + // input, we had `r` < `n` * R, so now `r` < 2 * `n` * R. Note that `r` + // includes `carry` which is stored separately. BN_ULONG n0 = mont->n0[0]; BN_ULONG carry = 0; for (size_t i = 0; i < num_n; i++) { @@ -206,11 +206,11 @@ a[i + num_n] = CRYPTO_addc_w(a[i + num_n], v, carry, &carry); } - // Shift |num_n| words to divide by R. We have |a| < 2 * |n|. Note that |a| - // includes |carry| which is stored separately. + // Shift `num_n` words to divide by R. We have `a` < 2 * `n`. Note that `a` + // includes `carry` which is stored separately. a += num_n; - // |a| thus requires at most one additional subtraction |n| to be reduced. + // `a` thus requires at most one additional subtraction `n` to be reduced. bn_reduce_once(r, a, carry, n, num_n); return 1; } @@ -251,8 +251,8 @@ int bssl::bn_one_to_montgomery(BIGNUM *r, const BN_MONT_CTX *mont, BN_CTX *ctx) { - // If the high bit of |n| is set, R = 2^(width*BN_BITS2) < 2 * |n|, so we - // compute R - |n| rather than perform Montgomery reduction. + // If the high bit of `n` is set, R = 2^(width*BN_BITS2) < 2 * `n`, so we + // compute R - `n` rather than perform Montgomery reduction. const BIGNUM *n = &mont->N; if (n->width > 0 && (n->d[n->width - 1] >> (BN_BITS2 - 1)) != 0) { if (!bn_wexpand(r, n->width)) { @@ -306,14 +306,14 @@ } #if defined(OPENSSL_BN_ASM_MONT) - // |bn_mul_mont_words| requires at least 128 bits of limbs. + // `bn_mul_mont_words` requires at least 128 bits of limbs. int num = mont->N.width; if (num >= (128 / BN_BITS2) && a->width == num && b->width == num) { if (!bn_wexpand(r, num)) { return 0; } - // This bound is implied by |bn_mont_ctx_set_N_and_n0|. |bn_mul_mont_words| - // allocates |num| words on the stack, so |num| cannot be too large. + // This bound is implied by `bn_mont_ctx_set_N_and_n0`. `bn_mul_mont_words` + // allocates `num` words on the stack, so `num` cannot be too large. assert((size_t)num <= BN_MONTGOMERY_MAX_WORDS); bn_mul_mont_words(r->d, a->d, b->d, mont->N.d, mont->n0, num); r->neg = 0; @@ -357,7 +357,7 @@ } #if defined(OPENSSL_BN_ASM_MONT) - // |bn_mul_mont_words| requires at least 128 bits of limbs. + // `bn_mul_mont_words` requires at least 128 bits of limbs. if (num >= (128 / BN_BITS2)) { bn_mul_mont_words(r, a, b, mont->N.d, mont->n0, num); return;
diff --git a/crypto/fipsmodule/bn/montgomery_inv.cc.inc b/crypto/fipsmodule/bn/montgomery_inv.cc.inc index e4ee089..3089f03 100644 --- a/crypto/fipsmodule/bn/montgomery_inv.cc.inc +++ b/crypto/fipsmodule/bn/montgomery_inv.cc.inc
@@ -30,30 +30,30 @@ "uint64_t is insufficient precision for n0"); uint64_t bssl::bn_mont_n0(const BIGNUM *n) { - // These conditions are checked by the caller, |BN_MONT_CTX_set| or - // |BN_MONT_CTX_new_consttime|. + // These conditions are checked by the caller, `BN_MONT_CTX_set` or + // `BN_MONT_CTX_new_consttime`. assert(!BN_is_zero(n)); assert(!BN_is_negative(n)); assert(BN_is_odd(n)); // r == 2**(BN_MONT_CTX_N0_LIMBS * BN_BITS2) ensures that we can do integer - // division by |r| by simply ignoring |BN_MONT_CTX_N0_LIMBS| limbs. Similarly, - // we can calculate values modulo |r| by just looking at the lowest - // |BN_MONT_CTX_N0_LIMBS| limbs. This is what makes Montgomery multiplication + // division by `r` by simply ignoring `BN_MONT_CTX_N0_LIMBS` limbs. Similarly, + // we can calculate values modulo `r` by just looking at the lowest + // `BN_MONT_CTX_N0_LIMBS` limbs. This is what makes Montgomery multiplication // efficient. // // As shown in Algorithm 1 of "Fast Prime Field Elliptic Curve Cryptography // with 256 Bit Primes" by Shay Gueron and Vlad Krasnov, in the loop of a - // multi-limb Montgomery multiplication of |a * b (mod n)|, given the - // unreduced product |t == a * b|, we repeatedly calculate: + // multi-limb Montgomery multiplication of `a * b (mod n)`, given the + // unreduced product `t == a * b`, we repeatedly calculate: // - // t1 := t % r |t1| is |t|'s lowest limb (see previous paragraph). + // t1 := t % r `t1` is `t`'s lowest limb (see previous paragraph). // t2 := t1*n0*n // t3 := t + t2 - // t := t3 / r copy all limbs of |t3| except the lowest to |t|. + // t := t3 / r copy all limbs of `t3` except the lowest to `t`. // // In the last step, it would only make sense to ignore the lowest limb of - // |t3| if it were zero. The middle steps ensure that this is the case: + // `t3` if it were zero. The middle steps ensure that this is the case: // // t3 == 0 (mod r) // t + t2 == 0 (mod r) @@ -64,10 +64,10 @@ // n0 == -1/n (mod r) // // Thus, in each iteration of the loop, we multiply by the constant factor - // |n0|, the negative inverse of n (mod r). + // `n0`, the negative inverse of n (mod r). // n_mod_r = n % r. As explained above, this is done by taking the lowest - // |BN_MONT_CTX_N0_LIMBS| limbs of |n|. + // `BN_MONT_CTX_N0_LIMBS` limbs of `n`. uint64_t n_mod_r = n->d[0]; #if BN_MONT_CTX_N0_LIMBS == 2 if (n->width > 1) { @@ -80,7 +80,7 @@ return bn_neg_inv_mod_u64(n_mod_r); } -// bn_neg_inv_mod_u64 calculates -1/n mod 2^64. |n| must be odd. +// bn_neg_inv_mod_u64 calculates -1/n mod 2^64. `n` must be odd. static uint64_t bn_neg_inv_mod_u64(uint64_t n) { // This is a modified version of the technique described in // https://crypto.stackexchange.com/a/47496 and
diff --git a/crypto/fipsmodule/bn/mul.cc.inc b/crypto/fipsmodule/bn/mul.cc.inc index 82746ad..3b3951f 100644 --- a/crypto/fipsmodule/bn/mul.cc.inc +++ b/crypto/fipsmodule/bn/mul.cc.inc
@@ -68,12 +68,12 @@ } // bn_sub_part_words sets |r| to |a| - |b|. It returns the borrow bit, which is -// one if the operation underflowed and zero otherwise. |cl| is the common -// length, that is, the shorter of len(a) or len(b). |dl| is the delta length, +// one if the operation underflowed and zero otherwise. `cl` is the common +// length, that is, the shorter of len(a) or len(b). `dl` is the delta length, // that is, len(a) - len(b). |r|'s length matches the larger of |a| and |b|, or // cl + abs(dl). // -// TODO(davidben): Make this take |size_t|. The |cl| + |dl| calling convention +// TODO(davidben): Make this take `size_t`. The `cl` + `dl` calling convention // is confusing. static BN_ULONG bn_sub_part_words(BN_ULONG *r, const BN_ULONG *a, const BN_ULONG *b, int cl, int dl) { @@ -88,15 +88,15 @@ b += cl; if (dl < 0) { - // |a| is shorter than |b|. Complete the subtraction as if the excess words - // in |a| were zeros. + // `a` is shorter than `b`. Complete the subtraction as if the excess words + // in `a` were zeros. dl = -dl; for (int i = 0; i < dl; i++) { r[i] = CRYPTO_subc_w(0, b[i], borrow, &borrow); } } else { - // |b| is shorter than |a|. Complete the subtraction as if the excess words - // in |b| were zeros. + // `b` is shorter than `a`. Complete the subtraction as if the excess words + // in `b` were zeros. for (int i = 0; i < dl; i++) { r[i] = CRYPTO_subc_w(a[i], 0, borrow, &borrow); } @@ -107,10 +107,10 @@ // bn_abs_sub_part_words computes |r| = |a| - |b|, storing the absolute value // and returning a mask of all ones if the result was negative and all zeros if -// the result was positive. |cl| and |dl| follow the |bn_sub_part_words| calling +// the result was positive. `cl` and `dl` follow the `bn_sub_part_words` calling // convention. // -// TODO(davidben): Make this take |size_t|. The |cl| + |dl| calling convention +// TODO(davidben): Make this take `size_t`. The `cl` + `dl` calling convention // is confusing. // // TODO(davidben): This function used to be used as part of a general Karatsuba @@ -144,8 +144,8 @@ return 1; } -// bn_mul_impl implements |BN_mul| and |bn_mul_consttime|. Note this function -// breaks |BIGNUM| invariants and may return a negative zero. This is handled by +// bn_mul_impl implements `BN_mul` and `bn_mul_consttime`. Note this function +// breaks `BIGNUM` invariants and may return a negative zero. This is handled by // the callers. static int bn_mul_impl(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx) { @@ -200,7 +200,7 @@ return 0; } - // This additionally fixes any negative zeros created by |bn_mul_impl|. + // This additionally fixes any negative zeros created by `bn_mul_impl`. bn_set_minimal_width(r); return 1; } @@ -221,7 +221,7 @@ if (num_r != num_a + num_b) { abort(); } - // TODO(davidben): Should this call |bn_mul_comba4| too? |BN_mul| does not + // TODO(davidben): Should this call `bn_mul_comba4` too? `BN_mul` does not // hit that code. if (num_a == 8 && num_b == 8) { bn_mul_comba8(r, a, b); @@ -255,10 +255,10 @@ } } - // The final result fits in |max| words, so none of the following operations + // The final result fits in `max` words, so none of the following operations // will overflow. - // Double |r|, giving the contribution of a[i] * a[j] for all i != j. + // Double `r`, giving the contribution of a[i] * a[j] for all i != j. bn_add_words(r, r, r, max); // Add in the contribution of a[i] * a[i] for all i.
diff --git a/crypto/fipsmodule/bn/prime.cc.inc b/crypto/fipsmodule/bn/prime.cc.inc index 14eac47..3e94d30 100644 --- a/crypto/fipsmodule/bn/prime.cc.inc +++ b/crypto/fipsmodule/bn/prime.cc.inc
@@ -204,9 +204,9 @@ } // BN_PRIME_CHECKS_BLINDED is the iteration count for blinding the constant-time -// primality test. See |BN_primality_test| for details. This number is selected -// so that, for a candidate N-bit RSA prime, picking |BN_PRIME_CHECKS_BLINDED| -// random N-bit numbers will have at least |BN_prime_checks_for_size(N)| values +// primality test. See `BN_primality_test` for details. This number is selected +// so that, for a candidate N-bit RSA prime, picking `BN_PRIME_CHECKS_BLINDED` +// random N-bit numbers will have at least `BN_prime_checks_for_size(N)` values // in range with high probability. // // The following Python script computes the blinding factor needed for the @@ -231,8 +231,8 @@ return r def failure_rate(min_uniform, iterations): - """ Returns the probability that, for |iterations| candidate witnesses, fewer - than |min_uniform| of them will be uniform. """ + """ Returns the probability that, for `iterations` candidate witnesses, fewer + than `min_uniform` of them will be uniform. """ prob = 0.0 for i in xrange(min_uniform): prob += (choose(iterations, i) * @@ -353,8 +353,8 @@ return 0; } - // Interleave |ret| and |t|'s primality tests to avoid paying the full - // iteration count on |ret| only to quickly discover |t| is composite. + // Interleave `ret` and `t`'s primality tests to avoid paying the full + // iteration count on `ret` only to quickly discover `t` is composite. // // TODO(davidben): This doesn't quite work because an iteration count of 1 // still runs the blinding mechanism. @@ -387,7 +387,7 @@ static int bn_trial_division(uint16_t *out, const BIGNUM *bn) { const size_t num_primes = num_trial_division_primes(bn); for (size_t i = 1; i < num_primes; i++) { - // During RSA key generation, |bn| may be secret, but only if |bn| was + // During RSA key generation, `bn` may be secret, but only if `bn` was // prime, so it is safe to leak failed trial divisions. if (constant_time_declassify_int(bn_mod_u16_consttime(bn, kPrimes[i]) == 0)) { @@ -407,7 +407,7 @@ const BN_MONT_CTX *mont, BN_CTX *ctx) { // This function corresponds to steps 1 through 3 of FIPS 186-5, B.3.1. const BIGNUM *w = &mont->N; - // Note we do not call |BN_CTX_start| in this function. We intentionally + // Note we do not call `BN_CTX_start` in this function. We intentionally // allocate values in the containing scope so they outlive this function. miller_rabin->w1 = BN_CTX_get(ctx); miller_rabin->m = BN_CTX_get(ctx); @@ -434,7 +434,7 @@ // Precompute some values in Montgomery form. if (!bn_one_to_montgomery(miller_rabin->one_mont, mont, ctx) || // w - 1 is -1 mod w, so we can compute it in the Montgomery domain, -R, - // with a subtraction. (|one_mont| cannot be zero.) + // with a subtraction. (`one_mont` cannot be zero.) !bn_usub_consttime(miller_rabin->w1_mont, w, miller_rabin->one_mont)) { return 0; } @@ -459,8 +459,8 @@ return 0; } - // is_possibly_prime is all ones if we have determined |b| is not a composite - // witness for |w|. This is equivalent to going to step 4.7 in the original + // is_possibly_prime is all ones if we have determined `b` is not a composite + // witness for `w`. This is equivalent to going to step 4.7 in the original // algorithm. To avoid timing leaks, we run the algorithm to the end for prime // inputs. is_possibly_prime = 0; @@ -473,8 +473,8 @@ // Step 4.5. // - // To avoid leaking |a|, we run the loop to |w_bits| and mask off all - // iterations once |j| = |a|. + // To avoid leaking `a`, we run the loop to `w_bits` and mask off all + // iterations once `j` = `a`. for (int j = 1; j < miller_rabin->w_bits; j++) { if (constant_time_declassify_w(constant_time_eq_int(j, miller_rabin->a) & ~is_possibly_prime)) { @@ -492,7 +492,7 @@ // witness. crypto_word_t z_is_w1_mont = BN_equal_consttime(z, miller_rabin->w1_mont); z_is_w1_mont = 0 - z_is_w1_mont; // Make it all zeros or all ones. - is_possibly_prime |= z_is_w1_mont; // Go to step 4.7 if |z_is_w1_mont|. + is_possibly_prime |= z_is_w1_mont; // Go to step 4.7 if `z_is_w1_mont`. // Step 4.5.3. If z = 1 and the loop is not done, the previous value of z // was not -1. There are no non-trivial square roots of 1 modulo a prime, so @@ -514,20 +514,20 @@ // generation. We generate RSA keys by selecting two large, secret primes with // rejection sampling. // - // We thus treat |w| as secret if turns out to be a large prime. However, if - // |w| is composite, we treat this and |w| itself as public. (Conversely, if - // |w| is prime, that it is prime is public. Only the value is secret.) This + // We thus treat `w` as secret if turns out to be a large prime. However, if + // `w` is composite, we treat this and `w` itself as public. (Conversely, if + // `w` is prime, that it is prime is public. Only the value is secret.) This // is fine for RSA key generation, but note it is important that we use // rejection sampling, with each candidate prime chosen independently. This // would not work for, e.g., an algorithm which looked for primes in // consecutive integers. These assumptions allow us to discard composites - // quickly. We additionally treat |w| as public when it is a small prime to + // quickly. We additionally treat `w` as public when it is a small prime to // simplify trial decryption and some edge cases. // // One RSA key generation will call this function on exactly two primes and // many more composites. The overall cost is a combination of several factors: // - // 1. Checking if |w| is divisible by a small prime is much faster than + // 1. Checking if `w` is divisible by a small prime is much faster than // learning it is composite by Miller-Rabin (see below for details on that // cost). Trial division by p saves 1/p of Miller-Rabin calls, so this is // worthwhile until p exceeds the ratio of the two costs. @@ -538,11 +538,11 @@ // trial decryption, in practice, cost one Miller-Rabin iteration. Only the // two actual primes cost the full iteration count. // - // 3. A Miller-Rabin iteration is a modular exponentiation plus |a| additional - // modular squares, where |a| is the number of factors of two in |w-1|. |a| + // 3. A Miller-Rabin iteration is a modular exponentiation plus `a` additional + // modular squares, where `a` is the number of factors of two in `w-1`. `a` // is likely small (the distribution falls exponentially), but it is also - // potentially secret, so we loop up to its log(w) upper bound when |w| is - // prime. When |w| is composite, we break early, so only two calls pay this + // potentially secret, so we loop up to its log(w) upper bound when `w` is + // prime. When `w` is composite, we break early, so only two calls pay this // cost. (Note that all calls pay the modular exponentiation which is, // itself, log(w) modular multiplications and squares.) // @@ -610,14 +610,14 @@ // The following loop performs in inner iteration of the Miller-Rabin // Primality test (Step 4). // - // The algorithm as specified in FIPS 186-5 leaks information on |w|, the RSA + // The algorithm as specified in FIPS 186-5 leaks information on `w`, the RSA // private key. Instead, we run through each iteration unconditionally, // performing modular multiplications, masking off any effects to behave // equivalently to the specified algorithm. // - // We also blind the number of values of |b| we try. Steps 4.1–4.2 say to - // discard out-of-range values. To avoid leaking information on |w|, we use - // |bn_rand_secret_range| which, rather than discarding bad values, adjusts + // We also blind the number of values of `b` we try. Steps 4.1–4.2 say to + // discard out-of-range values. To avoid leaking information on `w`, we use + // `bn_rand_secret_range` which, rather than discarding bad values, adjusts // them to be in range. Though not uniformly selected, these adjusted values // are still usable as Miller-Rabin checks. // @@ -628,14 +628,14 @@ // function is more complex and has more timing risk than necessary. // // We count both total iterations and uniform ones and iterate until we've - // reached at least |BN_PRIME_CHECKS_BLINDED| and |iterations|, respectively. + // reached at least `BN_PRIME_CHECKS_BLINDED` and `iterations`, respectively. // If the latter is large enough, it will be the limiting factor with high // probability and we won't leak information. // // Note this blinding does not impact most calls when picking primes because // composites are rejected early. Only the two secret primes see extra work. - // Using |constant_time_lt_w| seems to prevent the compiler from optimizing + // Using `constant_time_lt_w` seems to prevent the compiler from optimizing // this into two jumps. for (int i = 1; constant_time_declassify_w( (i <= BN_PRIME_CHECKS_BLINDED) |
diff --git a/crypto/fipsmodule/bn/random.cc.inc b/crypto/fipsmodule/bn/random.cc.inc index 591cb8f..1dbe27b 100644 --- a/crypto/fipsmodule/bn/random.cc.inc +++ b/crypto/fipsmodule/bn/random.cc.inc
@@ -94,7 +94,7 @@ } // bn_less_than_word_mask returns a mask of all ones if the number represented -// by |len| words at |a| is less than |b| and zero otherwise. It performs this +// by `len` words at |a| is less than |b| and zero otherwise. It performs this // computation in time independent of the value of |a|. |b| is assumed public. static crypto_word_t bn_less_than_word_mask(const BN_ULONG *a, size_t len, BN_ULONG b) { @@ -112,7 +112,7 @@ for (size_t i = 1; i < len; i++) { mask |= a[i]; } - // |mask| is now zero iff a[1..len-1] are all zero. + // `mask` is now zero iff a[1..len-1] are all zero. mask = constant_time_is_zero_w(mask); mask &= constant_time_lt_w(a[0], b); return mask; @@ -127,7 +127,7 @@ static int bn_range_to_mask(size_t *out_words, BN_ULONG *out_mask, size_t min_inclusive, const BN_ULONG *max_exclusive, size_t len) { - // The magnitude of |max_exclusive| is assumed public. + // The magnitude of `max_exclusive` is assumed public. size_t words = len; while (words > 0 && max_exclusive[words - 1] == 0) { words--; @@ -137,7 +137,7 @@ return 0; } BN_ULONG mask = max_exclusive[words - 1]; - // This sets all bits in |mask| below the most significant bit. + // This sets all bits in `mask` below the most significant bit. mask |= mask >> 1; mask |= mask >> 2; mask |= mask >> 4; @@ -157,10 +157,10 @@ const uint8_t additional_data[32]) { // This function implements the equivalent of steps 1 through 4 of FIPS 186-5 // appendices A.2.2 and A.3.2, repeating the process on failure. When called - // in those contexts, |max_exclusive| is n and |min_inclusive| is one. + // in those contexts, `max_exclusive` is n and `min_inclusive` is one. - // Compute the bit length of |max_exclusive| (step 1), in terms of a number of - // |words| worth of entropy to fill and a mask of bits to clear in the top + // Compute the bit length of `max_exclusive` (step 1), in terms of a number of + // `words` worth of entropy to fill and a mask of bits to clear in the top // word. size_t words; BN_ULONG mask; @@ -178,8 +178,8 @@ return 0; } - // Use |words| and |mask| together to obtain a string of N bits, where N is - // the bit length of |max_exclusive|. + // Use `words` and `mask` together to obtain a string of N bits, where N is + // the bit length of `max_exclusive`. FIPS_service_indicator_lock_state(); BCM_rand_bytes_with_additional_data( (uint8_t *)out, words * sizeof(BN_ULONG), additional_data); @@ -190,7 +190,7 @@ // comparison may be treated as public. It only reveals how many attempts // were needed before we found a value in range. This is independent of the // final secret output, and has a distribution that depends only on - // |min_inclusive| and |max_exclusive|, both of which are public. + // `min_inclusive` and `max_exclusive`, both of which are public. } while (!constant_time_declassify_int( bn_in_range_words(out, min_inclusive, max_exclusive, words))); return 1;
diff --git a/crypto/fipsmodule/bn/rsaz_exp.cc.inc b/crypto/fipsmodule/bn/rsaz_exp.cc.inc index 105daae..f81dccb 100644 --- a/crypto/fipsmodule/bn/rsaz_exp.cc.inc +++ b/crypto/fipsmodule/bn/rsaz_exp.cc.inc
@@ -52,7 +52,7 @@ assert((uintptr_t)storage % 64 == 0); BN_ULONG *a_inv, *m, *result, *table_s = storage + 40 * 3, *R2 = table_s; - // Note |R2| aliases |table_s|. + // Note `R2` aliases `table_s`. if (((((uintptr_t)storage & 4095) + 320) >> 12) != 0) { result = storage; a_inv = storage + 40; @@ -67,7 +67,7 @@ rsaz_1024_norm2red_avx2(a_inv, base_norm); rsaz_1024_norm2red_avx2(R2, RR); - // Convert |R2| from the usual radix, giving R = 2^1024, to RSAZ's radix, + // Convert `R2` from the usual radix, giving R = 2^1024, to RSAZ's radix, // giving R = 2^(36*29) = 2^1044. rsaz_1024_mul_avx2(R2, R2, R2, m, k0); // R2 = 2^2048 * 2^2048 / 2^1044 = 2^3052 @@ -119,7 +119,7 @@ wvalue = (wvalue >> (index % 8)) & 31; index -= 5; - rsaz_1024_gather5_avx2(a_inv, table_s, wvalue); // Borrow |a_inv|. + rsaz_1024_gather5_avx2(a_inv, table_s, wvalue); // Borrow `a_inv`. rsaz_1024_mul_avx2(result, result, a_inv, m, k0); } @@ -128,7 +128,7 @@ wvalue = p_str[0] & 15; - rsaz_1024_gather5_avx2(a_inv, table_s, wvalue); // Borrow |a_inv|. + rsaz_1024_gather5_avx2(a_inv, table_s, wvalue); // Borrow `a_inv`. rsaz_1024_mul_avx2(result, result, a_inv, m, k0); // Convert from Montgomery.
diff --git a/crypto/fipsmodule/bn/shift.cc.inc b/crypto/fipsmodule/bn/shift.cc.inc index 4799bac..bf96726 100644 --- a/crypto/fipsmodule/bn/shift.cc.inc +++ b/crypto/fipsmodule/bn/shift.cc.inc
@@ -263,7 +263,7 @@ int bits = 0; #if BN_BITS2 > 32 - // Check if the lower half of |x| are all zero. + // Check if the lower half of `x` are all zero. mask = constant_time_is_zero_w(l << (BN_BITS2 - 32)); // If the lower half is all zeros, it is included in the bit count and we // count the upper half. Otherwise, we count the lower half. @@ -311,7 +311,7 @@ ret |= first_nonzero & (i * BN_BITS2 + bits); } - // If got to the end of |bn| and saw no non-zero words, |bn| is zero. |ret| + // If got to the end of `bn` and saw no non-zero words, `bn` is zero. `ret` // will then remain zero. return ret; }
diff --git a/crypto/fipsmodule/cipher/aead.cc.inc b/crypto/fipsmodule/cipher/aead.cc.inc index 0e721ac..c27e4a7 100644 --- a/crypto/fipsmodule/cipher/aead.cc.inc +++ b/crypto/fipsmodule/cipher/aead.cc.inc
@@ -113,8 +113,8 @@ ctx->aead = nullptr; } -// check_alias returns 1 if |out| is compatible with |in| and 0 otherwise. If -// |in| and |out| alias, we require that |in| == |out|. +// check_alias returns 1 if `out` is compatible with `in` and 0 otherwise. If +// `in` and `out` alias, we require that `in` == `out`. static int check_alias(const uint8_t *in, size_t in_len, const uint8_t *out, size_t out_len) { if (!buffers_alias(in, in_len, out, out_len)) { @@ -178,7 +178,7 @@ } }); - // |out_tag| contains both the encryption of |extra_in| and the tag. + // `out_tag` contains both the encryption of `extra_in` and the tag. Span<uint8_t> out_tag_span(out_tag, max_out_tag_len); if (out_tag_span.size() < extra_in_len) { OPENSSL_PUT_ERROR(CIPHER, CIPHER_R_BUFFER_TOO_SMALL); @@ -338,7 +338,7 @@ } // Enforce aliasing rules: no output may alias any input, with the one - // exception that an iovec member's |in| and |out| pointers may be identical + // exception that an iovec member's `in` and `out` pointers may be identical // for in-place operation. if (!check_iovec_alias(iovecs, aadvecs, out_tag, max_out_tag_len, nonce, nonce_len, nullptr, 0)) { @@ -481,7 +481,7 @@ } // Enforce aliasing rules: no output may alias any input, with the one - // exception that an iovec member's |in| and |out| pointers may be identical + // exception that an iovec member's `in` and `out` pointers may be identical // for in-place operation. if (!check_iovec_alias(iovecs, aadvecs, nullptr, 0, nonce, nonce_len, nullptr, 0)) { @@ -499,7 +499,7 @@ std::optional<Span<const uint8_t>> tag = bssl::iovec::GetAndRemoveSuffix( Span(tagbuf).first(ctx->tag_len), Span(detached_iovecs)); - if (!tag.has_value()) { // I.e. no |ctx->tag_len| bytes available. + if (!tag.has_value()) { // I.e. no `ctx->tag_len` bytes available. OPENSSL_PUT_ERROR(CIPHER, CIPHER_R_BAD_DECRYPT); return 0; } @@ -554,7 +554,7 @@ } // Enforce aliasing rules: no output may alias any input, with the one - // exception that an iovec member's |in| and |out| pointers may be identical + // exception that an iovec member's `in` and `out` pointers may be identical // for in-place operation. if (!check_iovec_alias(iovecs, aadvecs, nullptr, 0, nonce, nonce_len, in_tag, in_tag_len)) {
diff --git a/crypto/fipsmodule/cipher/cipher.cc.inc b/crypto/fipsmodule/cipher/cipher.cc.inc index eed5d0a..d293f60 100644 --- a/crypto/fipsmodule/cipher/cipher.cc.inc +++ b/crypto/fipsmodule/cipher/cipher.cc.inc
@@ -206,10 +206,10 @@ return EVP_CipherInit_ex(ctx, cipher, impl, key, iv, 0); } -// block_remainder returns the number of bytes to remove from |len| to get a -// multiple of |ctx|'s block size. +// block_remainder returns the number of bytes to remove from `len` to get a +// multiple of `ctx`'s block size. static size_t block_remainder(const EVP_CIPHER_CTX *ctx, size_t len) { - // |block_size| must be a power of two. + // `block_size` must be a power of two. assert(ctx->cipher->block_size != 0); assert((ctx->cipher->block_size & (ctx->cipher->block_size - 1)) == 0); return len & (ctx->cipher->block_size - 1); @@ -245,13 +245,13 @@ template <typename F> static int WrapWithPoison(EVP_CIPHER_CTX *ctx, F f) { if (ctx->poisoned) { - // |ctx| has been left in an indeterminate state by a previous failed + // `ctx` has been left in an indeterminate state by a previous failed // operation. Do not allow proceeding. OPENSSL_PUT_ERROR(CIPHER, ERR_R_SHOULD_NOT_HAVE_BEEN_CALLED); return 0; } if (!f()) { - // Functions using |WrapWithPoison| may leave |ctx| in an indeterminate + // Functions using `WrapWithPoison` may leave `ctx` in an indeterminate // state. Mark the object as poisoned. ctx->poisoned = 1; return 0; @@ -264,8 +264,8 @@ const uint8_t *in, size_t in_len) { *out_len = 0; - // Ciphers that use blocks may write up to |block_size| extra bytes. Ensure - // the output does not overflow |*out_len|. + // Ciphers that use blocks may write up to `block_size` extra bytes. Ensure + // the output does not overflow `*out_len`. Span<const uint8_t> in_span(in, in_len); size_t block_size = ctx->cipher->block_size; @@ -422,8 +422,8 @@ const uint8_t *in, size_t in_len) { *out_len = 0; - // Ciphers that use blocks may write up to |block_size| extra bytes. Ensure - // the output does not overflow |*out_len|. + // Ciphers that use blocks may write up to `block_size` extra bytes. Ensure + // the output does not overflow `*out_len`. Span<const uint8_t> in_span(in, in_len); size_t block_size = ctx->cipher->block_size; @@ -614,15 +614,15 @@ out_len = in_len; } - // |EVP_CIPH_FLAG_CUSTOM_CIPHER| never sets the FIPS indicator via - // |EVP_Cipher| because it's complicated whether the operation has completed - // or not. E.g. AES-GCM with a non-NULL |in| argument hasn't completed an - // operation. Callers should use the |EVP_AEAD| API or, at least, - // |EVP_CipherUpdate| etc. + // `EVP_CIPH_FLAG_CUSTOM_CIPHER` never sets the FIPS indicator via + // `EVP_Cipher` because it's complicated whether the operation has completed + // or not. E.g. AES-GCM with a non-NULL `in` argument hasn't completed an + // operation. Callers should use the `EVP_AEAD` API or, at least, + // `EVP_CipherUpdate` etc. // - // This call can't be pushed into |EVP_Cipher_verify_service_indicator| - // because whether |ret| indicates success or not depends on whether - // |EVP_CIPH_FLAG_CUSTOM_CIPHER| is set. (This unreasonable, but matches + // This call can't be pushed into `EVP_Cipher_verify_service_indicator` + // because whether `ret` indicates success or not depends on whether + // `EVP_CIPH_FLAG_CUSTOM_CIPHER` is set. (This unreasonable, but matches // OpenSSL.) if (!(ctx->cipher->flags & EVP_CIPH_FLAG_CUSTOM_CIPHER)) { EVP_Cipher_verify_service_indicator(ctx);
diff --git a/crypto/fipsmodule/cipher/e_aes.cc.inc b/crypto/fipsmodule/cipher/e_aes.cc.inc index 9e88412..bfdb647 100644 --- a/crypto/fipsmodule/cipher/e_aes.cc.inc +++ b/crypto/fipsmodule/cipher/e_aes.cc.inc
@@ -93,7 +93,7 @@ if (ret == 0) { vpaes_decrypt_key_to_bsaes(&dat->ks.ks, &dat->ks.ks); } - // If |dat->stream.cbc| is provided, |dat->block| is never used. + // If `dat->stream.cbc` is provided, `dat->block` is never used. dat->block = nullptr; dat->stream.cbc = bsaes_cbc_encrypt; #endif @@ -330,7 +330,7 @@ } OPENSSL_memcpy(gctx->iv, ptr, arg); if (c->encrypt) { - // |BCM_rand_bytes| calls within the fipsmodule should be wrapped with + // `BCM_rand_bytes` calls within the fipsmodule should be wrapped with // state lock functions to avoid updating the service indicator with the // DRBG functions. FIPS_service_indicator_lock_state(); @@ -958,7 +958,7 @@ return 0; } - // |BCM_rand_bytes| calls within the fipsmodule should be wrapped with state + // `BCM_rand_bytes` calls within the fipsmodule should be wrapped with state // lock functions to avoid updating the service indicator with the DRBG // functions. FIPS_service_indicator_lock_state();
diff --git a/crypto/fipsmodule/cipher/e_aesccm.cc.inc b/crypto/fipsmodule/cipher/e_aesccm.cc.inc index f100cf9..de6bfd4 100644 --- a/crypto/fipsmodule/cipher/e_aesccm.cc.inc +++ b/crypto/fipsmodule/cipher/e_aesccm.cc.inc
@@ -67,7 +67,7 @@ const unsigned M = ctx->M; const unsigned L = ctx->L; - // |L| determines the expected |nonce_len| and the limit for |plaintext_len|. + // `L` determines the expected `nonce_len` and the limit for `plaintext_len`. if (plaintext_len > CRYPTO_ccm128_max_input(ctx)) { OPENSSL_PUT_ERROR(CIPHER, CIPHER_R_TOO_LARGE); return 0; @@ -155,8 +155,8 @@ return 0; } - // Assemble the first block for encrypting and decrypting. The bottom |L| - // bytes are replaced with a counter and all bit the encoding of |L| is + // Assemble the first block for encrypting and decrypting. The bottom `L` + // bytes are replaced with a counter and all bit the encoding of `L` is // cleared in the first byte. state->nonce[0] &= 7; return 1;
diff --git a/crypto/fipsmodule/cmac/cmac.cc.inc b/crypto/fipsmodule/cmac/cmac.cc.inc index 18d09af..93e48f8 100644 --- a/crypto/fipsmodule/cmac/cmac.cc.inc +++ b/crypto/fipsmodule/cmac/cmac.cc.inc
@@ -37,7 +37,7 @@ uint8_t k2[AES_BLOCK_SIZE]; // Last (possibly partial) scratch uint8_t block[AES_BLOCK_SIZE]; - // block_used contains the number of valid bytes in |block|. + // block_used contains the number of valid bytes in `block`. unsigned block_used; }; @@ -115,14 +115,14 @@ return 1; } -// binary_field_mul_x_128 treats the 128 bits at |in| as an element of GF(2¹²⁸) -// with a hard-coded reduction polynomial and sets |out| as x times the input. +// binary_field_mul_x_128 treats the 128 bits at `in` as an element of GF(2¹²⁸) +// with a hard-coded reduction polynomial and sets `out` as x times the input. // // See https://tools.ietf.org/html/rfc4493#section-2.3 static void binary_field_mul_x_128(uint8_t out[16], const uint8_t in[16]) { unsigned i; - // Shift |in| to left, including carry. + // Shift `in` to left, including carry. for (i = 0; i < 15; i++) { out[i] = (in[i] << 1) | (in[i + 1] >> 7); } @@ -132,14 +132,14 @@ out[i] = (in[i] << 1) ^ ((0 - carry) & 0x87); } -// binary_field_mul_x_64 behaves like |binary_field_mul_x_128| but acts on an +// binary_field_mul_x_64 behaves like `binary_field_mul_x_128` but acts on an // element of GF(2⁶⁴). // // See https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38b.pdf static void binary_field_mul_x_64(uint8_t out[8], const uint8_t in[8]) { unsigned i; - // Shift |in| to left, including carry. + // Shift `in` to left, including carry. for (i = 0; i < 7; i++) { out[i] = (in[i] << 1) | (in[i + 1] >> 7); } @@ -156,7 +156,7 @@ int ret = 0; uint8_t scratch[AES_BLOCK_SIZE]; - // We have to avoid the underlying AES-CBC |EVP_CIPHER| services updating the + // We have to avoid the underlying AES-CBC `EVP_CIPHER` services updating the // indicator state, so we lock the state here. FIPS_service_indicator_lock_state(); @@ -196,7 +196,7 @@ int CMAC_Update(CMAC_CTX *ctx, const uint8_t *in, size_t in_len) { int ret = 0; - // We have to avoid the underlying AES-CBC |EVP_Cipher| services updating the + // We have to avoid the underlying AES-CBC `EVP_Cipher` services updating the // indicator state, so we lock the state here. FIPS_service_indicator_lock_state(); @@ -215,9 +215,9 @@ in_len -= todo; ctx->block_used += todo; - // If |in_len| is zero then either |ctx->block_used| is less than - // |block_size|, in which case we can stop here, or |ctx->block_used| is - // exactly |block_size| but there's no more data to process. In the latter + // If `in_len` is zero then either `ctx->block_used` is less than + // `block_size`, in which case we can stop here, or `ctx->block_used` is + // exactly `block_size` but there's no more data to process. In the latter // case we don't want to process this block now because it might be the last // block and that block is treated specially. if (in_len == 0) { @@ -242,7 +242,7 @@ } OPENSSL_memcpy(ctx->block, in, in_len); - // |in_len| is bounded by |block_size|, which fits in |unsigned|. + // `in_len` is bounded by `block_size`, which fits in `unsigned`. static_assert(EVP_MAX_BLOCK_LENGTH < UINT_MAX, "EVP_MAX_BLOCK_LENGTH is too large"); ctx->block_used = (unsigned)in_len; @@ -258,7 +258,7 @@ size_t block_size = EVP_CIPHER_CTX_block_size(&ctx->cipher_ctx); assert(block_size <= AES_BLOCK_SIZE); - // We have to avoid the underlying AES-CBC |EVP_Cipher| services updating the + // We have to avoid the underlying AES-CBC `EVP_Cipher` services updating the // indicator state, so we lock the state here. FIPS_service_indicator_lock_state();
diff --git a/crypto/fipsmodule/dh/check.cc.inc b/crypto/fipsmodule/dh/check.cc.inc index ec8e358..0848819 100644 --- a/crypto/fipsmodule/dh/check.cc.inc +++ b/crypto/fipsmodule/dh/check.cc.inc
@@ -67,12 +67,12 @@ } BN_CTXScope scope(ctx.get()); - // Check |pub_key| is greater than 1. + // Check `pub_key` is greater than 1. if (BN_cmp(pub_key, BN_value_one()) <= 0) { *out_flags |= DH_CHECK_PUBKEY_TOO_SMALL; } - // Check |pub_key| is less than |impl->p| - 1. + // Check `pub_key` is less than `impl->p` - 1. BIGNUM *tmp = BN_CTX_get(ctx.get()); if (tmp == nullptr || !BN_copy(tmp, impl->p.get()) || !BN_sub_word(tmp, 1)) { return 0; @@ -82,9 +82,9 @@ } if (impl->q != nullptr) { - // Check |pub_key|^|impl->q| is 1 mod |impl->p|. This is necessary for RFC + // Check `pub_key`^`impl->q` is 1 mod `impl->p`. This is necessary for RFC // 5114 groups which are not safe primes but pick a generator on a - // prime-order subgroup of size |impl->q|. + // prime-order subgroup of size `impl->q`. if (!BN_mod_exp_mont(tmp, pub_key, impl->q.get(), impl->p.get(), ctx.get(), nullptr)) { return 0;
diff --git a/crypto/fipsmodule/dh/dh.cc.inc b/crypto/fipsmodule/dh/dh.cc.inc index 9837c6c..ca8351a 100644 --- a/crypto/fipsmodule/dh/dh.cc.inc +++ b/crypto/fipsmodule/dh/dh.cc.inc
@@ -145,7 +145,7 @@ } // Only generate a private key if there's already one. Otherwise, - // |DH_generate_key| recomputes the public key. + // `DH_generate_key` recomputes the public key. const BIGNUM *priv_key = impl->priv_key.get(); UniquePtr<BIGNUM> new_priv_key; if (priv_key == nullptr) { @@ -159,7 +159,7 @@ // from [1, min(2^N-1, q-1)]. // // Although SP 800-56A Rev3 now permits a private key length N, - // |impl->priv_length| historically was ignored when q is available. We + // `impl->priv_length` historically was ignored when q is available. We // continue to ignore it and interpret such a configuration as N = len(q). if (!BN_rand_range_ex(new_priv_key.get(), 1, impl->q.get())) { OPENSSL_PUT_ERROR(DH, ERR_R_BN_LIB); @@ -170,10 +170,10 @@ // the (p-1)/2 subgroup. So, we use q = (p-1)/2. (If g generates a smaller // prime-order subgroup, q will still divide (p-1)/2.) // - // We set N from |impl->priv_length|. Section 5.6.1.1.4 of SP 800-56A Rev3 + // We set N from `impl->priv_length`. Section 5.6.1.1.4 of SP 800-56A Rev3 // says to reject N > len(q), or N > num_bits(p) - 1. However, this logic // originally aligned with PKCS#3, which allows num_bits(p). Instead, we - // clamp |impl->priv_length| before invoking the algorithm. + // clamp `impl->priv_length` before invoking the algorithm. // Compute M = min(2^N, q). UniquePtr<BIGNUM> priv_key_limit(BN_new()); @@ -302,7 +302,7 @@ !dh_compute_key(dh, shared_key, peers_key, ctx.get())) { return -1; } - // A |BIGNUM|'s byte count fits in |int|. + // A `BIGNUM`'s byte count fits in `int`. return static_cast<int>(BN_bn2bin(shared_key, out)); } @@ -392,7 +392,7 @@ ffdhe2048_g.get())) { return nullptr; } - // |DH_set0_pqg| takes ownership on success. + // `DH_set0_pqg` takes ownership on success. ffdhe2048_p.release(); ffdhe2048_q.release(); ffdhe2048_g.release();
diff --git a/crypto/fipsmodule/digest/digest.cc.inc b/crypto/fipsmodule/digest/digest.cc.inc index 0973275..a7c6317 100644 --- a/crypto/fipsmodule/digest/digest.cc.inc +++ b/crypto/fipsmodule/digest/digest.cc.inc
@@ -93,8 +93,8 @@ void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags) {} int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in) { - // |in->digest| may be NULL if this is a signing |EVP_MD_CTX| for, e.g., - // Ed25519 which does not hash with |EVP_MD_CTX|. + // `in->digest` may be NULL if this is a signing `EVP_MD_CTX` for, e.g., + // Ed25519 which does not hash with `EVP_MD_CTX`. if (in == nullptr || (in->pctx == nullptr && in->digest == nullptr)) { OPENSSL_PUT_ERROR(DIGEST, DIGEST_R_INPUT_NOT_INITIALIZED); return 0; @@ -128,9 +128,9 @@ void EVP_MD_CTX_move(EVP_MD_CTX *out, EVP_MD_CTX *in) { EVP_MD_CTX_cleanup(out); - // While not guaranteed, |EVP_MD_CTX| is currently safe to move with |memcpy|. + // While not guaranteed, `EVP_MD_CTX` is currently safe to move with `memcpy`. // bssl-crypto currently relies on this, however, so if we change this, we - // need to box the |HMAC_CTX|. (Relying on this is only fine because we assume + // need to box the `HMAC_CTX`. (Relying on this is only fine because we assume // BoringSSL and bssl-crypto will always be updated atomically. We do not // allow any version skew between the two.) OPENSSL_memcpy(out, in, sizeof(EVP_MD_CTX));
diff --git a/crypto/fipsmodule/digestsign/digestsign.cc.inc b/crypto/fipsmodule/digestsign/digestsign.cc.inc index 3db794a..8920546 100644 --- a/crypto/fipsmodule/digestsign/digestsign.cc.inc +++ b/crypto/fipsmodule/digestsign/digestsign.cc.inc
@@ -176,8 +176,8 @@ int ret = 0; if (uses_prehash(ctx->pctx, evp_sign)) { - // If |out_sig| is NULL, the caller is only querying the maximum output - // length. |data| should only be incorporated in the final call. + // If `out_sig` is NULL, the caller is only querying the maximum output + // length. `data` should only be incorporated in the final call. if (out_sig != nullptr && !EVP_DigestSignUpdate(ctx, data, data_len)) { goto end; }
diff --git a/crypto/fipsmodule/ec/ec.cc.inc b/crypto/fipsmodule/ec/ec.cc.inc index 6d7507f..5c795d9 100644 --- a/crypto/fipsmodule/ec/ec.cc.inc +++ b/crypto/fipsmodule/ec/ec.cc.inc
@@ -183,7 +183,7 @@ ctx = new_ctx.get(); } - // Historically, |a| and |b| were not required to be fully reduced. + // Historically, `a` and `b` were not required to be fully reduced. // TODO(davidben): Can this be removed? BN_CTXScope scope(ctx); BIGNUM *a_reduced = BN_CTX_get(ctx); @@ -209,10 +209,10 @@ const BIGNUM *order, const BIGNUM *cofactor) { if (group->curve_name != NID_undef || group->has_order || generator->group != group) { - // |EC_GROUP_set_generator| may only be used with |EC_GROUP|s returned by - // |EC_GROUP_new_curve_GFp| and may only used once on each group. - // |generator| must have been created from |EC_GROUP_new_curve_GFp|, not a - // copy, so that |generator->group->generator| is set correctly. + // `EC_GROUP_set_generator` may only be used with `EC_GROUP`s returned by + // `EC_GROUP_new_curve_GFp` and may only used once on each group. + // `generator` must have been created from `EC_GROUP_new_curve_GFp`, not a + // copy, so that `generator->group->generator` is set correctly. OPENSSL_PUT_ERROR(EC, ERR_R_SHOULD_NOT_HAVE_BEEN_CALLED); return 0; } @@ -231,7 +231,7 @@ // Require that p < 2×order. This simplifies some ECDSA operations. // // Note any curve which did not satisfy this must have been invalid or use a - // tiny prime (less than 17). See the proof in |field_element_to_scalar| in + // tiny prime (less than 17). See the proof in `field_element_to_scalar` in // the ECDSA implementation. UniquePtr<BIGNUM> tmp(BN_new()); if (tmp == nullptr || !BN_lshift1(tmp.get(), order)) { @@ -251,7 +251,7 @@ group->field_greater_than_order = BN_cmp(&group->field.N, order) > 0; group->generator.raw.X = affine.X; group->generator.raw.Y = affine.Y; - // |raw.Z| was set to 1 by |EC_GROUP_new_curve_GFp|. + // `raw.Z` was set to 1 by `EC_GROUP_new_curve_GFp`. group->has_order = 1; return 1; } @@ -303,7 +303,7 @@ } auto *custom = static_cast<const ECCustomGroup *>(a); - // Groups are logically immutable (but for |EC_GROUP_set_generator| which must + // Groups are logically immutable (but for `EC_GROUP_set_generator` which must // be called early on), so we simply take a reference. ECCustomGroup *group = const_cast<ECCustomGroup *>(custom); group->UpRefInternal(); @@ -323,8 +323,8 @@ return 0; } - // |a| and |b| are both custom curves. We compare the entire curve - // structure. If |a| or |b| is incomplete (due to legacy OpenSSL mistakes, + // `a` and `b` are both custom curves. We compare the entire curve + // structure. If `a` or `b` is incomplete (due to legacy OpenSSL mistakes, // custom curve construction is sadly done in two parts) but otherwise not the // same object, we consider them always unequal. return a->meth != b->meth || // @@ -358,7 +358,7 @@ int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx) { - // All |EC_GROUP|s have cofactor 1. + // All `EC_GROUP`s have cofactor 1. return BN_set_word(cofactor, 1); } @@ -495,7 +495,7 @@ return -1; } - // Note |EC_POINT_cmp| returns zero for equality and non-zero for inequality. + // Note `EC_POINT_cmp` returns zero for equality and non-zero for inequality. return ec_GFp_simple_points_equal(group, &a->raw, &b->raw) ? 0 : 1; } @@ -661,7 +661,7 @@ int bssl::ec_point_mul_no_self_test(const EC_GROUP *group, EC_POINT *r, const BIGNUM *g_scalar, const EC_POINT *p, const BIGNUM *p_scalar, BN_CTX *ctx) { - // Previously, this function set |r| to the point at infinity if there was + // Previously, this function set `r` to the point at infinity if there was // nothing to multiply. But, nobody should be calling this function with // nothing to multiply in the first place. if ((g_scalar == nullptr && p_scalar == nullptr) || @@ -685,8 +685,8 @@ ctx = new_ctx.get(); } - // If both |g_scalar| and |p_scalar| are non-NULL, - // |ec_point_mul_scalar_public| would share the doublings between the two + // If both `g_scalar` and `p_scalar` are non-NULL, + // `ec_point_mul_scalar_public` would share the doublings between the two // products, which would be more efficient. However, we conservatively assume // the caller needs a constant-time operation. (ECDSA verification does not // use this function.) @@ -891,7 +891,7 @@ // order. These may not have the same size. However, we must have p < 2×order, // assuming p is not tiny (p >= 17). // - // Thus |bytes| will fit in |order.width + 1| words, and we can reduce by + // Thus `bytes` will fit in `order.width + 1` words, and we can reduce by // performing at most one subtraction. // // Proof: We only work with prime order curves, so the number of points on @@ -905,7 +905,7 @@ // p < 2×order // // Additionally, one can manually check this property for built-in curves. It - // is enforced for legacy custom curves in |EC_GROUP_set_generator|. + // is enforced for legacy custom curves in `EC_GROUP_set_generator`. const BIGNUM *order = EC_GROUP_get0_order(group); BN_ULONG words[EC_MAX_WORDS + 1] = {0}; bn_big_endian_to_words(words, order->width + 1, bytes, len); @@ -953,7 +953,7 @@ const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group) { // This function exists purely to give callers a way to call - // |EC_METHOD_get_field_type|. cryptography.io crashes if |EC_GROUP_method_of| + // `EC_METHOD_get_field_type`. cryptography.io crashes if `EC_GROUP_method_of` // returns NULL, so return some other garbage pointer. return (const EC_METHOD *)0x12340000; }
diff --git a/crypto/fipsmodule/ec/ec_key.cc.inc b/crypto/fipsmodule/ec/ec_key.cc.inc index e666baf..18979b9 100644 --- a/crypto/fipsmodule/ec/ec_key.cc.inc +++ b/crypto/fipsmodule/ec/ec_key.cc.inc
@@ -160,7 +160,7 @@ int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group) { auto *impl = FromOpaque(key); - // If |impl| already has a group, it is an error to switch to another one. + // If `impl` already has a group, it is an error to switch to another one. if (impl->group != nullptr) { if (EC_GROUP_cmp(impl->group, group, nullptr) != 0) { OPENSSL_PUT_ERROR(EC, EC_R_GROUP_MISMATCH); @@ -285,7 +285,7 @@ OPENSSL_PUT_ERROR(EC, ERR_R_EC_LIB); return 0; } - // Leaking this comparison only leaks whether |eckey|'s public key was + // Leaking this comparison only leaks whether `eckey`'s public key was // correct. if (!constant_time_declassify_int(ec_GFp_simple_points_equal( impl->group, &point, &impl->pub_key->raw))) { @@ -480,7 +480,7 @@ // The public key is derived from the private key, but it is public. // - // TODO(crbug.com/boringssl/677): This isn't quite right. While |pub_key| + // TODO(crbug.com/boringssl/677): This isn't quite right. While `pub_key` // represents a public point, it is still in Jacobian form and the exact // Jacobian representation is secret. We need to make it affine first. See // discussion in the bug.
diff --git a/crypto/fipsmodule/ec/ec_montgomery.cc.inc b/crypto/fipsmodule/ec/ec_montgomery.cc.inc index 4f1f1d3..ca2a8d4 100644 --- a/crypto/fipsmodule/ec/ec_montgomery.cc.inc +++ b/crypto/fipsmodule/ec/ec_montgomery.cc.inc
@@ -42,7 +42,7 @@ } // Transform (X, Y, Z) into (x, y) := (X/Z^2, Y/Z^3). Note the check above - // ensures |point->Z| is non-zero, so the inverse always exists. + // ensures `point->Z` is non-zero, so the inverse always exists. EC_FELEM z1, z2; ec_GFp_mont_felem_inv0(group, &z2, &point->Z); ec_felem_sqr(group, &z1, &z2); @@ -67,7 +67,7 @@ return 1; } - // Compute prefix products of all Zs. Use |out[i].X| as scratch space + // Compute prefix products of all Zs. Use `out[i].X` as scratch space // to store these values. out[0].X = in[0].Z; for (size_t i = 1; i < num; i++) { @@ -84,7 +84,7 @@ EC_FELEM zinvprod; ec_GFp_mont_felem_inv0(group, &zinvprod, &out[num - 1].X); for (size_t i = num - 1; i < num; i--) { - // Our loop invariant is that |zinvprod| is Z0^-1 * Z1^-1 * ... * Zi^-1. + // Our loop invariant is that `zinvprod` is Z0^-1 * Z1^-1 * ... * Zi^-1. // Recover Zi^-1 by multiplying by the previous product. EC_FELEM zinv, zinv2; if (i == 0) { @@ -174,7 +174,7 @@ BN_ULONG yneq = ec_felem_non_zero_mask(group, &r); - // This case will never occur in the constant-time |ec_GFp_mont_mul|. + // This case will never occur in the constant-time `ec_GFp_mont_mul`. BN_ULONG is_nontrivial_double = ~xneq & ~yneq & z1nz & z2nz; if (constant_time_declassify_w(is_nontrivial_double)) { ec_GFp_mont_dbl(group, out, a); @@ -341,7 +341,7 @@ // During signing the x coefficient is reduced modulo the group order. // Therefore there is a small possibility, less than 1/2^128, that group_order - // < p.x < P. in that case we need not only to compare against |r| but also to + // < p.x < P. in that case we need not only to compare against `r` but also to // compare against r+group_order. BN_ULONG carry = bn_add_words(r_Z2.words, r->words, group->order.N.d, group->field.N.width);
diff --git a/crypto/fipsmodule/ec/oct.cc.inc b/crypto/fipsmodule/ec/oct.cc.inc index 1ed7cbd..eb33277 100644 --- a/crypto/fipsmodule/ec/oct.cc.inc +++ b/crypto/fipsmodule/ec/oct.cc.inc
@@ -162,7 +162,7 @@ return 0; } if (buf == nullptr) { - // When |buf| is NULL, just return the number of bytes that would be + // When `buf` is NULL, just return the number of bytes that would be // written, without doing an expensive Jacobian-to-affine conversion. if (ec_GFp_simple_is_at_infinity(group, &point->raw)) { OPENSSL_PUT_ERROR(EC, EC_R_POINT_AT_INFINITY);
diff --git a/crypto/fipsmodule/ec/p256-nistz.cc.inc b/crypto/fipsmodule/ec/p256-nistz.cc.inc index 6200d07..0e2d282 100644 --- a/crypto/fipsmodule/ec/p256-nistz.cc.inc +++ b/crypto/fipsmodule/ec/p256-nistz.cc.inc
@@ -57,7 +57,7 @@ // Precomputed tables for the default generator #include "p256-nistz-table.h" -// Recode window to a signed digit, see |ec_GFp_nistp_recode_scalar_bits| in +// Recode window to a signed digit, see `ec_GFp_nistp_recode_scalar_bits` in // util.c for details static crypto_word_t booth_recode_w5(crypto_word_t in) { crypto_word_t s, d; @@ -81,8 +81,8 @@ return (d << 1) + (s & 1); } -// copy_conditional copies |src| to |dst| if |move| is one and leaves it as-is -// if |move| is zero. +// copy_conditional copies `src` to `dst` if `move` is one and leaves it as-is +// if `move` is zero. // // WARNING: this breaks the usual convention of constant-time functions // returning masks. @@ -215,7 +215,7 @@ } #endif // OPENSSL_X86_64 -// ecp_nistz256_from_mont sets |res| to |in|, converted from Montgomery domain +// ecp_nistz256_from_mont sets `res` to `in`, converted from Montgomery domain // by multiplying with 1. static void ecp_nistz256_from_mont(BN_ULONG res[P256_LIMBS], const BN_ULONG in[P256_LIMBS]) { @@ -223,8 +223,8 @@ ecp_nistz256_mul_mont(res, in, ONE); } -// ecp_nistz256_mod_inverse_sqr_mont sets |r| to (|in| * 2^-256)^-2 * 2^256 mod -// p. That is, |r| is the modular inverse square of |in| for input and output in +// ecp_nistz256_mod_inverse_sqr_mont sets `r` to (`in` * 2^-256)^-2 * 2^256 mod +// p. That is, `r` is the modular inverse square of `in` for input and output in // the Montgomery domain. static void ecp_nistz256_mod_inverse_sqr_mont(BN_ULONG r[P256_LIMBS], const BN_ULONG in[P256_LIMBS]) { @@ -303,8 +303,8 @@ static const size_t kWindowSize = 5; static const crypto_word_t kMask = (1 << (5 /* kWindowSize */ + 1)) - 1; - // A |P256_POINT| is (3 * 32) = 96 bytes, and the 64-byte alignment should - // add no more than 63 bytes of overhead. Thus, |table| should require + // A `P256_POINT` is (3 * 32) = 96 bytes, and the 64-byte alignment should + // add no more than 63 bytes of overhead. Thus, `table` should require // ~1599 ((96 * 16) + 63) bytes of stack space. alignas(64) P256_POINT table[16]; uint8_t p_str[33]; @@ -434,9 +434,9 @@ ecp_nistz256_neg(p.Z, t.Y); copy_conditional(t.Y, p.Z, wvalue & 1); - // Convert |t| from affine to Jacobian coordinates. We set Z to zero if |t| - // is infinity and |ONE_MONT| otherwise. |t| was computed from the table, so - // it is infinity iff |wvalue >> 1| is zero. + // Convert `t` from affine to Jacobian coordinates. We set Z to zero if `t` + // is infinity and `ONE_MONT` otherwise. `t` was computed from the table, so + // it is infinity iff `wvalue >> 1` is zero. OPENSSL_memcpy(p.X, t.X, sizeof(p.X)); OPENSSL_memcpy(p.Y, t.Y, sizeof(p.Y)); OPENSSL_memset(p.Z, 0, sizeof(p.Z)); @@ -451,7 +451,7 @@ ecp_nistz256_neg(neg_Y, t.Y); copy_conditional(t.Y, neg_Y, wvalue & 1); - // Note |ecp_nistz256_point_add_affine| does not work if |p| and |t| are the + // Note `ecp_nistz256_point_add_affine` does not work if `p` and `t` are the // same non-infinity point. ecp_nistz256_point_add_affine(&p, &p, &t); } @@ -478,9 +478,9 @@ size_t index = 0; size_t wvalue = calc_first_wvalue(&index, p_str); - // Convert |p| from affine to Jacobian coordinates. We set Z to zero if |p| - // is infinity and |ONE_MONT| otherwise. |p| was computed from the table, so - // it is infinity iff |wvalue >> 1| is zero. + // Convert `p` from affine to Jacobian coordinates. We set Z to zero if `p` + // is infinity and `ONE_MONT` otherwise. `p` was computed from the table, so + // it is infinity iff `wvalue >> 1` is zero. if ((wvalue >> 1) != 0) { OPENSSL_memcpy(p.X, &ecp_nistz256_precomputed[0][(wvalue >> 1) - 1].X, sizeof(p.X)); @@ -510,9 +510,9 @@ ecp_nistz256_neg(t.Y, t.Y); } - // Note |ecp_nistz256_point_add_affine| does not work if |p| and |t| are + // Note `ecp_nistz256_point_add_affine` does not work if `p` and `t` are // the same non-infinity point, so it is important that we compute the - // |g_scalar| term before the |p_scalar| term. + // `g_scalar` term before the `p_scalar` term. ecp_nistz256_point_add_affine(&p, &p, &t); } @@ -581,7 +581,7 @@ static void ecp_nistz256_inv0_mod_ord(const EC_GROUP *group, EC_SCALAR *out, const EC_SCALAR *in) { - // table[i] stores a power of |in| corresponding to the matching enum value. + // table[i] stores a power of `in` corresponding to the matching enum value. enum { // The following indices specify the power in binary. i_1 = 0, @@ -642,7 +642,7 @@ ecp_nistz256_ord_sqr_mont(table[i_x32], table[i_x16], 16); ecp_nistz256_ord_mul_mont(table[i_x32], table[i_x32], table[i_x16]); - // Compute |in| raised to the order-2. + // Compute `in` raised to the order-2. ecp_nistz256_ord_sqr_mont(out->words, table[i_x32], 64); ecp_nistz256_ord_mul_mont(out->words, out->words, table[i_x32]); static const struct { @@ -704,7 +704,7 @@ // During signing the x coefficient is reduced modulo the group order. // Therefore there is a small possibility, less than 1/2^128, that group_order - // < p.x < P. in that case we need not only to compare against |r| but also to + // < p.x < P. in that case we need not only to compare against `r` but also to // compare against r+group_order. BN_ULONG carry = bn_add_words(r_Z2, r->words, group->order.N.d, P256_LIMBS); if (carry == 0 && bn_less_than_words(r_Z2, group->field.N.d, P256_LIMBS)) {
diff --git a/crypto/fipsmodule/ec/p256.cc.inc b/crypto/fipsmodule/ec/p256.cc.inc index 49235c6..a67923d 100644 --- a/crypto/fipsmodule/ec/p256.cc.inc +++ b/crypto/fipsmodule/ec/p256.cc.inc
@@ -71,9 +71,9 @@ static void fiat_p256_from_words(fiat_p256_felem out, const BN_ULONG in[32 / sizeof(BN_ULONG)]) { - // Typically, |BN_ULONG| and |fiat_p256_limb_t| will be the same type, but on - // 64-bit platforms without |uint128_t|, they are different. However, on - // little-endian systems, |uint64_t[4]| and |uint32_t[8]| have the same + // Typically, `BN_ULONG` and `fiat_p256_limb_t` will be the same type, but on + // 64-bit platforms without `uint128_t`, they are different. However, on + // little-endian systems, `uint64_t[4]` and `uint32_t[8]` have the same // layout. OPENSSL_memcpy(out, in, 32); } @@ -83,11 +83,11 @@ } static void fiat_p256_to_generic(EC_FELEM *out, const fiat_p256_felem in) { - // See |fiat_p256_from_words|. + // See `fiat_p256_from_words`. OPENSSL_memcpy(out->words, in, 32); } -// fiat_p256_inv_square calculates |out| = |in|^{-2} +// fiat_p256_inv_square calculates `out` = `in`^{-2} // // Based on Fermat's Little Theorem: // a^p = a (mod p) @@ -204,8 +204,8 @@ } #include "./p256_table.h" -// fiat_p256_select_point_affine selects the |idx-1|th point from a -// precomputation table and copies it to out. If |idx| is zero, the output is +// fiat_p256_select_point_affine selects the `idx-1`th point from a +// precomputation table and copies it to out. If `idx` is zero, the output is // the point at infinity. static void fiat_p256_select_point_affine( const fiat_p256_limb_t idx, size_t size, @@ -219,7 +219,7 @@ fiat_p256_cmovznz(out[2], idx, out[2], fiat_p256_one); } -// fiat_p256_select_point selects the |idx|th point from a precomputation table +// fiat_p256_select_point selects the `idx`th point from a precomputation table // and copies it to out. static void fiat_p256_select_point(const fiat_p256_limb_t idx, size_t size, const fiat_p256_felem pre_comp[/*size*/][3], @@ -233,7 +233,7 @@ } } -// fiat_p256_get_bit returns the |i|th bit in |in|. +// fiat_p256_get_bit returns the `i`th bit in `in`. static crypto_word_t fiat_p256_get_bit(const EC_SCALAR *in, int i) { if (i < 0 || i >= 256) { return 0; @@ -335,7 +335,7 @@ // Set nq to the point at infinity. fiat_p256_felem nq[3] = {{0}, {0}, {0}}, ftmp, tmp[3]; - // Loop over |scalar| msb-to-lsb, incorporating |p_pre_comp| every 5th round. + // Loop over `scalar` msb-to-lsb, incorporating `p_pre_comp` every 5th round. int skip = 1; // Save two point operations in the first round. for (size_t i = 255; i < 256; i--) { // double @@ -431,7 +431,7 @@ const EC_JACOBIAN *p, const EC_SCALAR *p_scalar) { #define P256_WSIZE_PUBLIC 4 - // Precompute multiples of |p|. p_pre_comp[i] is (2*i+1) * |p|. + // Precompute multiples of `p`. p_pre_comp[i] is (2*i+1) * `p`. fiat_p256_felem p_pre_comp[1 << (P256_WSIZE_PUBLIC - 1)][3]; fiat_p256_from_generic(p_pre_comp[0][0], &p->X); fiat_p256_from_generic(p_pre_comp[0][1], &p->Y); @@ -445,11 +445,11 @@ p_pre_comp[i - 1][2], p2[0], p2[1], p2[2]); } - // Set up the coefficients for |p_scalar|. + // Set up the coefficients for `p_scalar`. int8_t p_wNAF[257]; ec_compute_wNAF(group, p_wNAF, p_scalar, 256, P256_WSIZE_PUBLIC); - // Set |ret| to the point at infinity. + // Set `ret` to the point at infinity. int skip = 1; // Save some point operations. fiat_p256_felem ret[3] = {{0}, {0}, {0}}; for (int i = 256; i >= 0; i--) { @@ -457,7 +457,7 @@ fiat_p256_point_double(ret[0], ret[1], ret[2], ret[0], ret[1], ret[2]); } - // For the |g_scalar|, we use the precomputed table without the + // For the `g_scalar`, we use the precomputed table without the // constant-time lookup. if (i <= 31) { // First, look 32 bits upwards. @@ -541,7 +541,7 @@ // During signing the x coefficient is reduced modulo the group order. // Therefore there is a small possibility, less than 1/2^128, that group_order - // < p.x < P. in that case we need not only to compare against |r| but also to + // < p.x < P. in that case we need not only to compare against `r` but also to // compare against r+group_order. assert(group->field.N.width == group->order.N.width); EC_FELEM tmp;
diff --git a/crypto/fipsmodule/ec/scalar.cc.inc b/crypto/fipsmodule/ec/scalar.cc.inc index 9581325..f8b0642 100644 --- a/crypto/fipsmodule/ec/scalar.cc.inc +++ b/crypto/fipsmodule/ec/scalar.cc.inc
@@ -164,8 +164,8 @@ // even though for this interface it is not mandatory. // r = a^-1 in the Montgomery domain. This is - // |ec_scalar_to_montgomery| followed by |ec_scalar_inv0_montgomery|, but - // |ec_scalar_inv0_montgomery| followed by |ec_scalar_from_montgomery| is + // `ec_scalar_to_montgomery` followed by `ec_scalar_inv0_montgomery`, but + // `ec_scalar_inv0_montgomery` followed by `ec_scalar_from_montgomery` is // equivalent and slightly more efficient. ec_scalar_inv0_montgomery(group, r, a); ec_scalar_from_montgomery(group, r, r);
diff --git a/crypto/fipsmodule/ec/simple.cc.inc b/crypto/fipsmodule/ec/simple.cc.inc index bd3dd1e..3095ef7 100644 --- a/crypto/fipsmodule/ec/simple.cc.inc +++ b/crypto/fipsmodule/ec/simple.cc.inc
@@ -99,7 +99,7 @@ void bssl::ec_GFp_simple_point_set_to_infinity(const EC_GROUP *group, EC_JACOBIAN *point) { // Although it is strictly only necessary to zero Z, we zero the entire point - // in case |point| was stack-allocated and yet to be initialized. + // in case `point` was stack-allocated and yet to be initialized. ec_GFp_simple_point_init(point); } @@ -177,7 +177,7 @@ // restore this optimization by keeping better track of affine vs. Jacobian // forms. See https://crbug.com/boringssl/326. - // If neither |a| or |b| is infinity, we have to decide whether + // If neither `a` or `b` is infinity, we have to decide whether // (X_a/Z_a^2, Y_a/Z_a^3) = (X_b/Z_b^2, Y_b/Z_b^3), // or equivalently, whether // (X_a*Z_b^2, Y_a*Z_b^3) = (X_b*Z_a^2, Y_b*Z_a^3). @@ -209,7 +209,7 @@ int bssl::ec_affine_jacobian_equal(const EC_GROUP *group, const EC_AFFINE *a, const EC_JACOBIAN *b) { - // If |b| is not infinity, we have to decide whether + // If `b` is not infinity, we have to decide whether // (X_a, Y_a) = (X_b/Z_b^2, Y_b/Z_b^3), // or equivalently, whether // (X_a*Z_b^2, Y_a*Z_b^3) = (X_b, Y_b). @@ -236,7 +236,7 @@ const EC_JACOBIAN *p, const EC_SCALAR *r) { if (ec_GFp_simple_is_at_infinity(group, p)) { - // |ec_get_x_coordinate_as_scalar| will check this internally, but this way + // `ec_get_x_coordinate_as_scalar` will check this internally, but this way // we do not push to the error queue. return 0; }
diff --git a/crypto/fipsmodule/ec/simple_mul.cc.inc b/crypto/fipsmodule/ec/simple_mul.cc.inc index e4a665f..baff127 100644 --- a/crypto/fipsmodule/ec/simple_mul.cc.inc +++ b/crypto/fipsmodule/ec/simple_mul.cc.inc
@@ -30,9 +30,9 @@ const EC_JACOBIAN *p, const EC_SCALAR *scalar) { // This is a generic implementation for uncommon curves that not do not // warrant a tuned one. It uses unsigned digits so that the doubling case in - // |ec_GFp_mont_add| is always unreachable, erring on safety and simplicity. + // `ec_GFp_mont_add` is always unreachable, erring on safety and simplicity. - // Compute a table of the first 32 multiples of |p| (including infinity). + // Compute a table of the first 32 multiples of `p` (including infinity). EC_JACOBIAN precomp[32]; ec_GFp_simple_point_set_to_infinity(group, &precomp[0]); ec_GFp_simple_point_copy(&precomp[1], p); @@ -44,7 +44,7 @@ } } - // Divide bits in |scalar| into windows. + // Divide bits in `scalar` into windows. unsigned bits = EC_GROUP_order_bits(group); int r_is_at_infinity = 1; for (unsigned i = bits - 1; i < bits; i--) { @@ -142,7 +142,7 @@ ec_GFp_mont_batch_precomp(group, precomp[2], 17, p2); } - // Divide bits in |scalar| into windows. + // Divide bits in `scalar` into windows. unsigned bits = EC_GROUP_order_bits(group); int r_is_at_infinity = 1; for (unsigned i = bits; i <= bits; i--) { @@ -183,7 +183,7 @@ // comb[i - 1] stores the ith element of the comb. That is, if i is // b4 * 2^4 + b3 * 2^3 + ... + b0 * 2^0, it stores k * |p|, where k is // b4 * 2^(4*stride) + b3 * 2^(3*stride) + ... + b0 * 2^(0*stride). stride - // here is |ec_GFp_mont_comb_stride|. We store at index i - 1 because the 0th + // here is `ec_GFp_mont_comb_stride`. We store at index i - 1 because the 0th // comb entry is always infinity. EC_JACOBIAN comb[(1 << EC_MONT_PRECOMP_COMB_SIZE) - 1]; unsigned stride = ec_GFp_mont_comb_stride(group); @@ -192,7 +192,7 @@ // entries up to 2^0 are filled. comb[(1 << 0) - 1] = *p; for (unsigned i = 1; i < EC_MONT_PRECOMP_COMB_SIZE; i++) { - // Compute entry 2^i by doubling the entry for 2^(i-1) |stride| times. + // Compute entry 2^i by doubling the entry for 2^(i-1) `stride` times. unsigned bit = 1 << i; ec_GFp_mont_dbl(group, &comb[bit - 1], &comb[bit / 2 - 1]); for (unsigned j = 1; j < stride; j++) { @@ -219,15 +219,15 @@ const EC_SCALAR *scalar, unsigned i) { const size_t width = group->order.N.width; unsigned stride = ec_GFp_mont_comb_stride(group); - // Select the bits corresponding to the comb shifted up by |i|. + // Select the bits corresponding to the comb shifted up by `i`. unsigned window = 0; for (unsigned j = 0; j < EC_MONT_PRECOMP_COMB_SIZE; j++) { window |= bn_is_bit_set_words(scalar->words, width, j * stride + i) << j; } - // Select precomp->comb[window - 1]. If |window| is zero, |match| will always - // be zero, which will leave |out| at infinity. + // Select precomp->comb[window - 1]. If `window` is zero, `match` will always + // be zero, which will leave `out` at infinity. OPENSSL_memset(out, 0, sizeof(EC_JACOBIAN)); for (unsigned j = 0; j < std::size(precomp->comb); j++) { BN_ULONG match = constant_time_eq_w(window, j + 1);
diff --git a/crypto/fipsmodule/ec/util.cc.inc b/crypto/fipsmodule/ec/util.cc.inc index 5b98ae0..8ca2406 100644 --- a/crypto/fipsmodule/ec/util.cc.inc +++ b/crypto/fipsmodule/ec/util.cc.inc
@@ -110,7 +110,7 @@ // is a prime that is much larger than 2^w. It also only holds when windows // are applied from most significant to least significant, doubling between each // window. It does not apply to more complex table strategies such as -// |EC_GFp_nistz256_method|. +// `EC_GFp_nistz256_method`. // // PROOF: //
diff --git a/crypto/fipsmodule/ec/wnaf.cc.inc b/crypto/fipsmodule/ec/wnaf.cc.inc index 74def20..2592e79 100644 --- a/crypto/fipsmodule/ec/wnaf.cc.inc +++ b/crypto/fipsmodule/ec/wnaf.cc.inc
@@ -85,8 +85,8 @@ out[j] = digit; - // Incorporate the next bit. Previously, |window_val| <= |next_bit|, so if - // we shift and add at most one copy of |bit|, this will continue to hold + // Incorporate the next bit. Previously, `window_val` <= `next_bit`, so if + // we shift and add at most one copy of `bit`, this will continue to hold // afterwards. window_val >>= 1; window_val += bit * bn_is_bit_set_words(scalar->words, group->order.N.width, @@ -98,7 +98,7 @@ assert(window_val == 0); } -// compute_precomp sets |out[i]| to (2*i+1)*p, for i from 0 to |len|. +// compute_precomp sets `out[i]` to (2*i+1)*p, for i from 0 to `len`. static void compute_precomp(const EC_GROUP *group, EC_JACOBIAN *out, const EC_JACOBIAN *p, size_t len) { ec_GFp_simple_point_copy(&out[0], p); @@ -120,10 +120,10 @@ } } -// EC_WNAF_WINDOW_BITS is the window size to use for |ec_GFp_mont_mul_public|. +// EC_WNAF_WINDOW_BITS is the window size to use for `ec_GFp_mont_mul_public`. #define EC_WNAF_WINDOW_BITS 4 -// EC_WNAF_TABLE_SIZE is the table size to use for |ec_GFp_mont_mul_public|. +// EC_WNAF_TABLE_SIZE is the table size to use for `ec_GFp_mont_mul_public`. #define EC_WNAF_TABLE_SIZE (1 << (EC_WNAF_WINDOW_BITS - 1)) // EC_WNAF_STACK is the number of points worth of data to stack-allocate and
diff --git a/crypto/fipsmodule/ecdsa/ecdsa.cc.inc b/crypto/fipsmodule/ecdsa/ecdsa.cc.inc index 463fc66..b44fbd4 100644 --- a/crypto/fipsmodule/ecdsa/ecdsa.cc.inc +++ b/crypto/fipsmodule/ecdsa/ecdsa.cc.inc
@@ -31,7 +31,7 @@ using namespace bssl; -// digest_to_scalar interprets |digest_len| bytes from |digest| as a scalar for +// digest_to_scalar interprets `digest_len` bytes from `digest` as a scalar for // ECDSA. static void digest_to_scalar(const EC_GROUP *group, EC_SCALAR *out, const uint8_t *digest, size_t digest_len) { @@ -49,8 +49,8 @@ bn_rshift_words(out->words, out->words, 8 - (num_bits & 0x7), order->width); } - // |out| now has the same bit width as |order|, but this only bounds by - // 2*|order|. Subtract the order if out of range. + // `out` now has the same bit width as `order`, but this only bounds by + // 2*`order`. Subtract the order if out of range. // // Montgomery multiplication accepts the looser bounds, so this isn't strictly // necessary, but it is a cleaner abstraction and has no performance impact. @@ -89,8 +89,8 @@ // u1 = m * s^-1 mod order // u2 = r * s^-1 mod order // - // |s_inv_mont| is in Montgomery form while |m| and |r| are not, so |u1| and - // |u2| will be taken out of Montgomery form, as desired. + // `s_inv_mont` is in Montgomery form while `m` and `r` are not, so `u1` and + // `u2` will be taken out of Montgomery form, as desired. digest_to_scalar(group, &m, digest, digest_len); ec_scalar_mul_montgomery(group, &u1, &m, &s_inv_mont); ec_scalar_mul_montgomery(group, &u2, &r, &s_inv_mont); @@ -144,7 +144,7 @@ } // s = priv_key * r. Note if only one parameter is in the Montgomery domain, - // |ec_scalar_mod_mul_montgomery| will compute the answer in the normal + // `ec_scalar_mod_mul_montgomery` will compute the answer in the normal // domain. EC_SCALAR s; ec_scalar_to_montgomery(group, &s, &r); @@ -156,9 +156,9 @@ ec_scalar_add(group, &s, &s, &tmp); // s = k^-1 * (m + priv_key * r). First, we compute k^-1 in the Montgomery - // domain. This is |ec_scalar_to_montgomery| followed by - // |ec_scalar_inv0_montgomery|, but |ec_scalar_inv0_montgomery| followed by - // |ec_scalar_from_montgomery| is equivalent and slightly more efficient. + // domain. This is `ec_scalar_to_montgomery` followed by + // `ec_scalar_inv0_montgomery`, but `ec_scalar_inv0_montgomery` followed by + // `ec_scalar_from_montgomery` is equivalent and slightly more efficient. // Then, as above, only one parameter is in the Montgomery domain, so the // result is in the normal domain. Finally, note k is non-zero (or computing r // would fail), so the inverse must exist. @@ -264,7 +264,7 @@ goto out; } - // TODO(davidben): Move this inside |ec_random_nonzero_scalar| or lower, so + // TODO(davidben): Move this inside `ec_random_nonzero_scalar` or lower, so // that all scalars we generate are, by default, secret. CONSTTIME_SECRET(k.words, sizeof(k.words));
diff --git a/crypto/fipsmodule/entropy/sha512.cc.inc b/crypto/fipsmodule/entropy/sha512.cc.inc index 53512a8..1d954d0 100644 --- a/crypto/fipsmodule/entropy/sha512.cc.inc +++ b/crypto/fipsmodule/entropy/sha512.cc.inc
@@ -74,8 +74,8 @@ } void SHA384_Final(uint8_t out[kSHA384DigestLength], SHA512_CTX *sha) { - // This function must be paired with |SHA384_Init|, which sets - // |sha->md_len| to |kSHA384DigestLength|. + // This function must be paired with `SHA384_Init`, which sets + // `sha->md_len` to `kSHA384DigestLength`. sha512_final_impl(out, kSHA384DigestLength, sha); return; }
diff --git a/crypto/fipsmodule/hmac/hmac.cc.inc b/crypto/fipsmodule/hmac/hmac.cc.inc index 6211760..c753fae 100644 --- a/crypto/fipsmodule/hmac/hmac.cc.inc +++ b/crypto/fipsmodule/hmac/hmac.cc.inc
@@ -98,10 +98,10 @@ md = ctx->md; } - // If either |key| is non-NULL or |md| has changed, initialize with a new key + // If either `key` is non-NULL or `md` has changed, initialize with a new key // rather than rewinding the previous one. // - // TODO(davidben,eroman): Passing the previous |md| with a NULL |key| is + // TODO(davidben,eroman): Passing the previous `md` with a NULL `key` is // ambiguous between using the empty key and reusing the previous key. There // exist callers which intend the latter, but the former is an awkward edge // case. Fix to API to avoid this. @@ -165,7 +165,7 @@ FIPS_service_indicator_lock_state(); // TODO(davidben): The only thing that can officially fail here is - // |EVP_MD_CTX_copy_ex|, but even that should be impossible in this case. + // `EVP_MD_CTX_copy_ex`, but even that should be impossible in this case. if (!EVP_DigestFinal_ex(&ctx->md_ctx, buf, &i) || !EVP_MD_CTX_copy_ex(&ctx->md_ctx, &ctx->o_ctx) || !EVP_DigestUpdate(&ctx->md_ctx, buf, i) ||
diff --git a/crypto/fipsmodule/keccak/keccak.cc.inc b/crypto/fipsmodule/keccak/keccak.cc.inc index 5008cd4..264c741 100644 --- a/crypto/fipsmodule/keccak/keccak.cc.inc +++ b/crypto/fipsmodule/keccak/keccak.cc.inc
@@ -232,8 +232,8 @@ } const size_t rate_words = ctx->rate_bytes / 8; - // XOR the input. Accessing |ctx->state| as a |uint8_t*| is allowed by strict - // aliasing because we require |uint8_t| to be a character type. + // XOR the input. Accessing `ctx->state` as a `uint8_t*` is allowed by strict + // aliasing because we require `uint8_t` to be a character type. uint8_t *state_bytes = (uint8_t *)ctx->state; // Absorb partial block. @@ -287,8 +287,8 @@ } static void keccak_finalize(struct BORINGSSL_keccak_st *ctx) { - // XOR the terminator. Accessing |ctx->state| as a |uint8_t*| is allowed by - // strict aliasing because we require |uint8_t| to be a character type. + // XOR the terminator. Accessing `ctx->state` as a `uint8_t*` is allowed by + // strict aliasing because we require `uint8_t` to be a character type. uint8_t *state_bytes = (uint8_t *)ctx->state; state_bytes[ctx->absorb_offset] ^= keccak_terminator(ctx); state_bytes[ctx->rate_bytes - 1] ^= 0x80; @@ -298,8 +298,8 @@ #if defined(HAVE_KECCAK_X2) static void keccak_finalize_x2(struct BORINGSSL_keccak_st ctx[2]) { for (size_t i = 0; i < 2; ++i) { - // XOR the terminator. Accessing |ctx->state| as a |uint8_t*| is allowed by - // strict aliasing because we require |uint8_t| to be a character type. + // XOR the terminator. Accessing `ctx->state` as a `uint8_t*` is allowed by + // strict aliasing because we require `uint8_t` to be a character type. uint8_t *state_bytes = (uint8_t *)ctx[i].state; state_bytes[ctx[i].absorb_offset] ^= keccak_terminator(&ctx[i]); state_bytes[ctx[i].rate_bytes - 1] ^= 0x80; @@ -323,8 +323,8 @@ ctx->phase = boringssl_keccak_phase_squeeze; } - // Accessing |ctx->state| as a |uint8_t*| is allowed by strict aliasing - // because we require |uint8_t| to be a character type. + // Accessing `ctx->state` as a `uint8_t*` is allowed by strict aliasing + // because we require `uint8_t` to be a character type. const uint8_t *state_bytes = (const uint8_t *)ctx->state; while (out_len) { if (ctx->squeeze_offset == ctx->rate_bytes) { @@ -375,8 +375,8 @@ ctx->phase = boringssl_keccak_phase_squeeze; } - // Accessing |ctx->state| as a |uint8_t*| is allowed by strict aliasing - // because we require |uint8_t| to be a character type. + // Accessing `ctx->state` as a `uint8_t*` is allowed by strict aliasing + // because we require `uint8_t` to be a character type. uint8_t *optr[2] = {outs[0], outs[1]}; while (out_len) { if (ctx->squeeze_offset == ctx->rate_bytes) {
diff --git a/crypto/fipsmodule/mldsa/mldsa.cc.inc b/crypto/fipsmodule/mldsa/mldsa.cc.inc index 4bd3885..5562431 100644 --- a/crypto/fipsmodule/mldsa/mldsa.cc.inc +++ b/crypto/fipsmodule/mldsa/mldsa.cc.inc
@@ -303,7 +303,7 @@ // We usually add value barriers to selects because Clang turns consecutive // selects with the same condition into a branch instead of CMOV/CSEL. This // condition does not occur in ML-DSA, so omitting it seems to be generally - // safe. However, see |coefficient_from_nibble|. + // safe. However, see `coefficient_from_nibble`. return (mask & x) | (~mask & subtracted); } @@ -341,7 +341,7 @@ uint32_t r = a - b; // return r < 0 ? r + kPrime : r; uint32_t mask = 0u - (r >> 31); - // See |reduce_once| for why this does not have a value barrier. + // See `reduce_once` for why this does not have a value barrier. return (mask & (r + kPrime)) | (~mask & r); } @@ -388,9 +388,9 @@ const uint32_t step_root = kNTTRootsMontgomery[step + i]; for (int j = k; j < k + offset; j++) { uint32_t even = s->c[j]; - // |reduce_montgomery| works on values up to kPrime*R and R > 2*kPrime. - // |step_root| < kPrime because it's static data. |s->c[...]| is < - // kPrime by the invariants of that struct. + // `reduce_montgomery` works on values up to kPrime*R and R > 2*kPrime. + // `step_root` < kPrime because it's static data. + // `s->c[...]` is < kPrime by the invariants of that struct. uint32_t odd = reduce_montgomery((uint64_t)step_root * (uint64_t)s->c[j + offset]); s->c[j] = reduce_once(odd + even); @@ -420,11 +420,11 @@ uint32_t odd = s->c[j + offset]; s->c[j] = reduce_once(odd + even); - // |reduce_montgomery| works on values up to kPrime*R and R > 2*kPrime. - // kPrime + even < 2*kPrime because |even| < kPrime, by the invariants + // `reduce_montgomery` works on values up to kPrime*R and R > 2*kPrime. + // kPrime + even < 2*kPrime because `even` < kPrime, by the invariants // of that structure. Thus kPrime + even - odd < 2*kPrime because odd >= // 0, because it's unsigned and less than kPrime. Lastly step_root < - // kPrime, because |kNTTRootsMontgomery| is static data. + // kPrime, because `kNTTRootsMontgomery` is static data. s->c[j + offset] = reduce_montgomery((uint64_t)step_root * (uint64_t)(kPrime + even - odd)); } @@ -600,8 +600,8 @@ if (h) { if constexpr (prime_minus_one_over_gamma2<K>() == 32) { if (r0 > 0) { - // (Q-1)/(2 gamma2) = m = 16, thus |mod m| in the spec turns into |& - // 15|. + // (Q-1)/(2 gamma2) = m = 16, thus `mod m` in the spec turns into + // `& 15`. return (r1 + 1) & 15; } else { return (r1 - 1) & 15; @@ -1170,8 +1170,8 @@ template <> inline bool coefficient_from_nibble<4>(uint32_t nibble, uint32_t *result) { if (constant_time_declassify_int(nibble < 9)) { - // Knowing bounds on |nibble| seems to tempt some versions of Clang to emit - // a branch, if we don't have a barrier in |mod_sub|. + // Knowing bounds on `nibble` seems to tempt some versions of Clang to emit + // a branch, if we don't have a barrier in `mod_sub`. *result = mod_sub(4, value_barrier_u32(nibble)); return true; } @@ -1181,8 +1181,8 @@ template <> inline bool coefficient_from_nibble<2>(uint32_t nibble, uint32_t *result) { if (constant_time_declassify_int(nibble < 15)) { - // Knowing bounds on |nibble| seems to tempt some versions of Clang to emit - // a branch, if we don't have a barrier in |mod_sub|. + // Knowing bounds on `nibble` seems to tempt some versions of Clang to emit + // a branch, if we don't have a barrier in `mod_sub`. // Constant time "nibble % 5". nibble = nibble - 5 * ((205 * nibble) >> 10); *result = mod_sub(2, value_barrier_u32(nibble)); @@ -1338,7 +1338,7 @@ // FIPS 204, Algorithm 16 (`SimpleBitPack`). // -// Encodes an entire vector into 32*K*|bits| bytes. Note that since 256 +// Encodes an entire vector into 32*K*`bits` bytes. Note that since 256 // (kDegree) is divisible by 8, the individual vector entries will always fill a // whole number of bytes, so we do not need to worry about bit packing here. template <int K> @@ -1369,7 +1369,7 @@ // FIPS 204, Algorithm 17 (`BitPack`). // -// Encodes an entire vector into 32*L*|bits| bytes. Note that since 256 +// Encodes an entire vector into 32*L*`bits` bytes. Note that since 256 // (kDegree) is divisible by 8, the individual vector entries will always fill a // whole number of bytes, so we do not need to worry about bit packing here. template <int X> @@ -1804,7 +1804,7 @@ // https://pq-crystals.org/dilithium/data/dilithium-specification-round3.pdf // describes this leak as OK. Note we leak less than what is described by // the paper; we do not reveal which coefficient violated the bound, and - // we hide which of the |z_max| or |r0_max| bound failed. See also + // we hide which of the `z_max` or `r0_max` bound failed. See also // https://boringssl-review.googlesource.com/c/boringssl/+/67747/comment/2bbab0fa_d241d35a/ uint32_t z_max = vector_max(&values->sign.z); uint32_t r0_max = vector_max_signed(r0); @@ -2324,8 +2324,8 @@ mldsa::fips::check_key(mldsa::private_key_from_external_65(private_key))); } -// Calls |MLDSA_generate_key_external_entropy| with random bytes from -// |BCM_rand_bytes|. +// Calls `MLDSA_generate_key_external_entropy` with random bytes from +// `BCM_rand_bytes`. bcm_status bssl::BCM_mldsa65_generate_key( uint8_t out_encoded_public_key[MLDSA65_PUBLIC_KEY_BYTES], uint8_t out_seed[MLDSA_SEED_BYTES], MLDSA65_private_key *out_private_key) { @@ -2429,7 +2429,7 @@ } // ML-DSA signature in randomized mode, filling the random bytes with -// |BCM_rand_bytes|. +// `BCM_rand_bytes`. bcm_status bssl::BCM_mldsa65_sign( uint8_t out_encoded_signature[MLDSA65_SIGNATURE_BYTES], const MLDSA65_private_key *private_key, const uint8_t *msg, size_t msg_len, @@ -2528,7 +2528,7 @@ const MLDSA65_public_key *b) { auto *a_pub = mldsa::public_key_from_external_65(a); auto *b_pub = mldsa::public_key_from_external_65(b); - // It is sufficient to compare |public_key_hash|. When importing a public key, + // It is sufficient to compare `public_key_hash`. When importing a public key, // the hash must be computed. When importing a private key in expanded form // (an internal testing-only API), the hash is provided, but we recompute it // and check for correctness. @@ -2564,8 +2564,8 @@ mldsa::fips::check_key(mldsa::private_key_from_external_87(private_key))); } -// Calls |MLDSA_generate_key_external_entropy| with random bytes from -// |BCM_rand_bytes|. +// Calls `MLDSA_generate_key_external_entropy` with random bytes from +// `BCM_rand_bytes`. bcm_status bssl::BCM_mldsa87_generate_key( uint8_t out_encoded_public_key[MLDSA87_PUBLIC_KEY_BYTES], uint8_t out_seed[MLDSA_SEED_BYTES], MLDSA87_private_key *out_private_key) { @@ -2669,7 +2669,7 @@ } // ML-DSA signature in randomized mode, filling the random bytes with -// |BCM_rand_bytes|. +// `BCM_rand_bytes`. bcm_status bssl::BCM_mldsa87_sign( uint8_t out_encoded_signature[MLDSA87_SIGNATURE_BYTES], const MLDSA87_private_key *private_key, const uint8_t *msg, size_t msg_len, @@ -2769,7 +2769,7 @@ const MLDSA87_public_key *b) { auto *a_pub = mldsa::public_key_from_external_87(a); auto *b_pub = mldsa::public_key_from_external_87(b); - // It is sufficient to compare |public_key_hash|. When importing a public key, + // It is sufficient to compare `public_key_hash`. When importing a public key, // the hash must be computed. When importing a private key in expanded form // (an internal testing-only API), the hash is provided, but we recompute it // and check for correctness. @@ -2805,8 +2805,8 @@ mldsa::fips::check_key(mldsa::private_key_from_external_44(private_key))); } -// Calls |MLDSA_generate_key_external_entropy| with random bytes from -// |BCM_rand_bytes|. +// Calls `MLDSA_generate_key_external_entropy` with random bytes from +// `BCM_rand_bytes`. bcm_status bssl::BCM_mldsa44_generate_key( uint8_t out_encoded_public_key[MLDSA44_PUBLIC_KEY_BYTES], uint8_t out_seed[MLDSA_SEED_BYTES], MLDSA44_private_key *out_private_key) { @@ -2910,7 +2910,7 @@ } // ML-DSA signature in randomized mode, filling the random bytes with -// |BCM_rand_bytes|. +// `BCM_rand_bytes`. bcm_status bssl::BCM_mldsa44_sign( uint8_t out_encoded_signature[MLDSA44_SIGNATURE_BYTES], const MLDSA44_private_key *private_key, const uint8_t *msg, size_t msg_len, @@ -3010,7 +3010,7 @@ const MLDSA44_public_key *b) { auto *a_pub = mldsa::public_key_from_external_44(a); auto *b_pub = mldsa::public_key_from_external_44(b); - // It is sufficient to compare |public_key_hash|. When importing a public key, + // It is sufficient to compare `public_key_hash`. When importing a public key, // the hash must be computed. When importing a private key in expanded form // (an internal testing-only API), the hash is provided, but we recompute it // and check for correctness.
diff --git a/crypto/fipsmodule/mlkem/mlkem.cc.inc b/crypto/fipsmodule/mlkem/mlkem.cc.inc index 540b5b3..a73d5d9 100644 --- a/crypto/fipsmodule/mlkem/mlkem.cc.inc +++ b/crypto/fipsmodule/mlkem/mlkem.cc.inc
@@ -212,7 +212,7 @@ // We usually add value barriers to selects because Clang turns consecutive // selects with the same condition into a branch instead of CMOV/CSEL. This // condition does not occur in ML-KEM, so omitting it seems to be safe so far, - // but see |scalar_centered_binomial_distribution_eta_2_with_prf|. + // but see `scalar_centered_binomial_distribution_eta_2_with_prf`. return (mask & x) | (~mask & subtracted); } @@ -236,9 +236,9 @@ // In place number theoretic transform of a given scalar. // Note that MLKEM's kPrime 3329 does not have a 512th root of unity, so this // transform leaves off the last iteration of the usual FFT code, with the 128 -// relevant roots of unity being stored in |kNTTRoots|. This means the output +// relevant roots of unity being stored in `kNTTRoots`. This means the output // should be seen as 128 elements in GF(3329^2), with the coefficients of the -// elements being consecutive entries in |s->c|. +// elements being consecutive entries in `s->c`. inline void scalar_ntt(scalar *s) { // Manually unrolled loop to maximize vectorization. #define ITER(step, offset) \ @@ -278,7 +278,7 @@ // entries of s->v being interpreted as elements of GF(3329^2). Just as with the // number theoretic transform, this leaves off the first step of the normal iFFT // to account for the fact that 3329 does not have a 512th root of unity, using -// the precomputed 128 roots of unity stored in |kInverseNTTRoots|. +// the precomputed 128 roots of unity stored in `kInverseNTTRoots`. void scalar_inverse_ntt(scalar *s) { // Manually unrolled loop to maximize vectorization. #define ITER(step, offset) \ @@ -334,7 +334,7 @@ // 3329 does not have a 512th root of unity, this means we have to interpret // the 2*ith and (2*i+1)th entries of the scalar as elements of GF(3329)[X]/(X^2 // - 17^(2*bitreverse(i)+1)) The value of 17^(2*bitreverse(i)+1) mod 3329 is -// stored in the precomputed |kModRoots| table. Note that our Barrett transform +// stored in the precomputed `kModRoots` table. Note that our Barrett transform // only allows us to multiply two reduced numbers together, so we need some // intermediate reduction steps, even if an uint64_t could hold 3 multiplied // numbers. @@ -452,10 +452,10 @@ uint16_t value = (byte & 1) + ((byte >> 1) & 1); value -= ((byte >> 2) & 1) + ((byte >> 3) & 1); - // Add |kPrime| if |value| underflowed. See |reduce_once| for a discussion + // Add `kPrime` if `value` underflowed. See `reduce_once` for a discussion // on why the value barrier is omitted. While this could have been written // reduce_once(value + kPrime), this is one extra addition and small range - // of |value| tempts some versions of Clang to emit a branch. + // of `value` tempts some versions of Clang to emit a branch. uint16_t mask = 0u - (value >> 15); out->c[i] = ((value + kPrime) & mask) | (value & ~mask); @@ -469,7 +469,7 @@ } // Algorithm 8 from the spec, with eta fixed to two and the PRF call -// included. Creates binominally distributed elements by sampling 2*|eta| bits, +// included. Creates binominally distributed elements by sampling 2*`eta` bits, // and setting the coefficient to the count of the first bits minus the count of // the second bits, resulting in a centered binomial distribution. Since eta is // two this gives -2/2 with a probability of 1/16, -1/1 with probability 1/4, @@ -505,8 +505,8 @@ #endif // Generates a secret vector by using -// |scalar_centered_binomial_distribution_eta_2_with_prf|, using the given seed -// appending and incrementing |counter| for entry of the vector. +// `scalar_centered_binomial_distribution_eta_2_with_prf`, using the given seed +// appending and incrementing `counter` for entry of the vector. template <int RANK> void vector_generate_secret_eta_2(vector<RANK> *out, uint8_t *counter, const uint8_t seed[32]) { @@ -576,9 +576,9 @@ } } -// Encodes a scalar of 256 |BITS|-bit words into 32*|BITS| bytes by splitting +// Encodes a scalar of 256 `BITS`-bit words into 32*`BITS` bytes by splitting // and joining into bytes using LSB-first bit order (i.e. opposite to standard -// reading order). See below for examples. If an input is >= 1 << |BITS|, the +// reading order). See below for examples. If an input is >= 1 << `BITS`, the // result is undefined. template <int BITS> void scalar_encode(uint8_t *out, const scalar *s); @@ -704,7 +704,7 @@ } } -// Encodes an entire vector into 32*|RANK|*|bits| bytes. Note that since 256 +// Encodes an entire vector into 32*`RANK`*`bits` bytes. Note that since 256 // (DEGREE) is divisible by 8, the individual vector entries will always fill a // whole number of bytes, so we do not need to worry about bit packing here. template <int bits, int RANK> @@ -714,9 +714,9 @@ } } -// The inverse of |scalar_encode|. Returns 1 iff the encoded scalar is valid, -// i.e. all components are < |kPrime|. Otherwise, returns 0 and the value of -// |out| is undefined. +// The inverse of `scalar_encode`. Returns 1 iff the encoded scalar is valid, +// i.e. all components are < `kPrime`. Otherwise, returns 0 and the value of +// `out` is undefined. template <int BITS> int scalar_decode(scalar *out, const uint8_t *in); @@ -766,9 +766,9 @@ return 1; } -// scalar_decode parses |DEGREE * bits| bits from |in| into |DEGREE| values in -// |out|. It returns one on success and zero if any parsed value is >= -// |kPrime|. +// scalar_decode parses `DEGREE * bits` bits from `in` into `DEGREE` values in +// `out`. It returns one on success and zero if any parsed value is >= +// `kPrime`. template <> int scalar_decode<11>(scalar *out, const uint8_t in[352]) { for (int i = 0; i < DEGREE; i += 8) { @@ -831,8 +831,8 @@ return 1; } -// Decodes 32*|RANK|*|bits| bytes from |in| into |out|. It returns one on -// success or zero if any parsed value is >= |kPrime|. +// Decodes 32*`RANK`*`bits` bytes from `in` into `out`. It returns one on +// success or zero if any parsed value is >= `kPrime`. template <int bits, int RANK> inline int vector_decode(vector<RANK> *out, const uint8_t *in) { for (int i = 0; i < RANK; i++) { @@ -843,12 +843,12 @@ return 1; } -// Compresses (lossily) an input |x| mod 3329 into |bits| many bits by grouping +// Compresses (lossily) an input `x` mod 3329 into `bits` many bits by grouping // numbers close to each other together. The formula used is -// round(2^|bits|/kPrime*x) mod 2^|bits|. +// round(2^`bits`/kPrime*x) mod 2^`bits`. // Uses Barrett reduction to achieve constant time. Since we need both the // remainder (for rounding) and the quotient (as the result), we cannot use -// |reduce| here, but need to do the Barrett reduction directly. +// `reduce` here, but need to do the Barrett reduction directly. inline uint16_t compress(uint16_t x, int bits) { uint32_t shifted = (uint32_t)x << bits; uint64_t product = (uint64_t)shifted * kBarrettMultiplier; @@ -865,19 +865,19 @@ return quotient & ((1 << bits) - 1); } -// Decompresses |x| by using an equi-distant representative. The formula is -// round(kPrime/2^|bits|*x). Note that 2^|bits| being the divisor allows us to +// Decompresses `x` by using an equi-distant representative. The formula is +// round(kPrime/2^`bits`*x). Note that 2^`bits` being the divisor allows us to // implement this logic using only bit operations. inline uint16_t decompress(uint16_t x, int bits) { uint32_t product = (uint32_t)x * kPrime; uint32_t power = 1 << bits; - // This is |product| % power, since |power| is a power of 2. + // This is `product` % power, since `power` is a power of 2. uint32_t remainder = product & (power - 1); - // This is |product| / power, since |power| is a power of 2. + // This is `product` / power, since `power` is a power of 2. uint32_t lower = product >> bits; - // The rounding logic works since the first half of numbers mod |power| have a - // 0 as first bit, and the second half has a 1 as first bit, since |power| is - // a power of 2. As a 12 bit number, |remainder| is always positive, so we + // The rounding logic works since the first half of numbers mod `power` have a + // 0 as first bit, and the second half has a 1 as first bit, since `power` is + // a power of 2. As a 12 bit number, `remainder` is always positive, so we // will shift in 0s for a right shift. return lower + (remainder >> (bits - 1)); } @@ -1012,7 +1012,7 @@ } // Encrypts a message with given randomness to -// the ciphertext in |out|. Without applying the Fujisaki-Okamoto transform this +// the ciphertext in `out`. Without applying the Fujisaki-Okamoto transform this // would not result in a CCA secure scheme, since lattice schemes are vulnerable // to decryption failure oracles. template <int RANK> @@ -1085,8 +1085,8 @@ mlkem_decap_no_self_test(out_shared_secret, ciphertext, priv); } -// mlkem_parse_public_key_with_trailing_data parses |in| into |pub| but leaves -// trailing data in |in| for the caller. +// mlkem_parse_public_key_with_trailing_data parses `in` into `pub` but leaves +// trailing data in `in` for the caller. template <int RANK> int mlkem_parse_public_key_with_trailing_data(public_key<RANK> *pub, CBS *in) { CBS orig_in = *in; @@ -1527,8 +1527,8 @@ return mlkem::public_key_1024_to_external(&priv->pub); } -// Calls |MLKEM768_encap_external_entropy| with random bytes from -// |BCM_rand_bytes| +// Calls `MLKEM768_encap_external_entropy` with random bytes from +// `BCM_rand_bytes` bcm_infallible bssl::BCM_mlkem768_encap( uint8_t out_ciphertext[MLKEM768_CIPHERTEXT_BYTES], uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES],
diff --git a/crypto/fipsmodule/rand/android_entropy_client.cc.inc b/crypto/fipsmodule/rand/android_entropy_client.cc.inc index c31ebfb..1611052 100644 --- a/crypto/fipsmodule/rand/android_entropy_client.cc.inc +++ b/crypto/fipsmodule/rand/android_entropy_client.cc.inc
@@ -59,7 +59,7 @@ } if (done != BSSL_ENTROPY_DAEMON_RESPONSE_LEN) { - // The daemon should always write |BSSL_ENTROPY_DAEMON_RESPONSE_LEN| bytes + // The daemon should always write `BSSL_ENTROPY_DAEMON_RESPONSE_LEN` bytes // on every connection. goto out; }
diff --git a/crypto/fipsmodule/rand/ctrdrbg.cc.inc b/crypto/fipsmodule/rand/ctrdrbg.cc.inc index 04f5195..8aa034c 100644 --- a/crypto/fipsmodule/rand/ctrdrbg.cc.inc +++ b/crypto/fipsmodule/rand/ctrdrbg.cc.inc
@@ -241,7 +241,7 @@ static_assert(CTR_DRBG_SEED_LEN % AES_BLOCK_SIZE == 0, "not a multiple of AES block size"); -// ctr_inc adds |n| to the last four bytes of |drbg->counter|, treated as a +// ctr_inc adds `n` to the last four bytes of `drbg->counter`, treated as a // big-endian number. static void ctr32_add(CTR_DRBG_STATE *drbg, uint32_t n) { uint32_t ctr = CRYPTO_load_u32_be(drbg->counter + 12);
diff --git a/crypto/fipsmodule/rand/rand.cc.inc b/crypto/fipsmodule/rand/rand.cc.inc index dad1f2b..5d4fc9f 100644 --- a/crypto/fipsmodule/rand/rand.cc.inc +++ b/crypto/fipsmodule/rand/rand.cc.inc
@@ -44,8 +44,8 @@ // Each thread gets its own, thread-local DRBG. These are `rand_thread_state` // objects. In non-FIPS mode these are seeded from the operating system. It's // assumed that the operating system always has an unfailing source of entropy -// which is accessed via |CRYPTO_sysrand|. (If the operating system entropy -// source fails, it's up to |CRYPTO_sysrand| to abort the process—we don't try +// which is accessed via `CRYPTO_sysrand`. (If the operating system entropy +// source fails, it's up to `CRYPTO_sysrand` to abort the process—we don't try // to handle it.) // // If running in FIPS mode, a compliant entropy source must be used to seed the @@ -81,8 +81,8 @@ struct core_drbg { CTR_DRBG_STATE drbg; - // calls is the number of generate calls made on |drbg| since it was last - // (re)seeded. This is bound by |kCoreReseedInterval|. + // calls is the number of generate calls made on `drbg` since it was last + // (re)seeded. This is bound by `kCoreReseedInterval`. uint64_t calls = 0; }; @@ -187,10 +187,10 @@ struct rand_thread_state { CTR_DRBG_STATE drbg; uint64_t fork_generation; - // calls is the number of generate calls made on |drbg| since it was last - // (re)seeded. This is bound by |kReseedInterval|. + // calls is the number of generate calls made on `drbg` since it was last + // (re)seeded. This is bound by `kReseedInterval`. unsigned calls; - // fork_unsafe_buffering is non-zero iff, when |drbg| was last (re)seeded, + // fork_unsafe_buffering is non-zero iff, when `drbg` was last (re)seeded, // fork-unsafe buffering was enabled. int fork_unsafe_buffering; @@ -198,8 +198,8 @@ // next and prev form a nullptr-terminated, double-linked list of all states // in a process. struct rand_thread_state *next, *prev; - // clear_drbg_lock synchronizes between uses of |drbg| and - // |rand_thread_state_clear_all| clearing it. This lock should be uncontended + // clear_drbg_lock synchronizes between uses of `drbg` and + // `rand_thread_state_clear_all` clearing it. This lock should be uncontended // in the common case, except on shutdown. Mutex clear_drbg_lock; #endif @@ -208,7 +208,7 @@ } // namespace #if defined(BORINGSSL_FIPS) -// thread_states_list is the head of a linked-list of all |rand_thread_state| +// thread_states_list is the head of a linked-list of all `rand_thread_state` // objects in the process, one per thread. This is needed because FIPS requires // the ability to zero them on demand (AS09.28). BoringSSL triggers this with a // destructor function. @@ -231,13 +231,13 @@ } // The locks are deliberately left locked so that any threads that are still - // running will hang if they try to call |BCM_rand_bytes|. It also ensures - // |rand_thread_state_free| cannot free any thread state while we've taken the + // running will hang if they try to call `BCM_rand_bytes`. It also ensures + // `rand_thread_state_free` cannot free any thread state while we've taken the // lock. } #endif -// rand_thread_state_free frees a |rand_thread_state|. This is called when a +// rand_thread_state_free frees a `rand_thread_state`. This is called when a // thread exits. static void rand_thread_state_free(void *state_in) { struct rand_thread_state *state = @@ -253,8 +253,8 @@ if (state->prev != nullptr) { state->prev->next = state->next; } else if (*thread_states_list_bss_get() == state) { - // |state->prev| may be nullptr either if it is the head of the list, - // or if |state| is freed before it was added to the list at all. + // `state->prev` may be nullptr either if it is the head of the list, + // or if `state` is freed before it was added to the list at all. // Compare against the head of the list to distinguish these cases. *thread_states_list_bss_get() = state->next; } @@ -273,7 +273,7 @@ #if defined(OPENSSL_X86_64) && !defined(OPENSSL_NO_ASM) && \ !defined(FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION) -// rdrand should only be called if either |have_rdrand| or |have_fast_rdrand| +// rdrand should only be called if either `have_rdrand` or `have_fast_rdrand` // returned true. static int rdrand(uint8_t *buf, const size_t len) { const size_t len_multiple8 = len & ~7; @@ -313,7 +313,7 @@ #if defined(BORINGSSL_FIPS) -// rand_get_seed fills |seed| with entropy. Since, in FIPS mode, this entropy +// rand_get_seed fills `seed` with entropy. Since, in FIPS mode, this entropy // comes from the jitter source / system daemon, `additional_input` will also be // filled with system entropy. static void rand_get_seed(struct rand_thread_state *state, @@ -327,7 +327,7 @@ #else -// rand_get_seed fills |seed| with system entropy in a non-FIPS build. +// rand_get_seed fills `seed` with system entropy in a non-FIPS build. static void rand_get_seed(struct rand_thread_state *state, uint8_t seed[CTR_DRBG_ENTROPY_LEN], uint8_t additional_input[CTR_DRBG_SEED_LEN], @@ -357,7 +357,7 @@ if (!have_fast_rdrand() || !rdrand(additional_data, sizeof(additional_data))) { // Without a hardware RNG to save us from address-space duplication, the OS - // entropy is used. This can be expensive (one read per |RAND_bytes| call) + // entropy is used. This can be expensive (one read per `RAND_bytes` call) // and so is disabled when we have fork detection, or if the application has // promised not to fork. if (fork_generation != 0 || fork_unsafe_buffering) { @@ -416,10 +416,10 @@ } if (state->calls >= kReseedInterval || - // If we've forked since |state| was last seeded, reseed. + // If we've forked since `state` was last seeded, reseed. state->fork_generation != fork_generation || - // If |state| was seeded from a state with different fork-safety - // preferences, reseed. Suppose |state| was fork-safe, then forked into + // If `state` was seeded from a state with different fork-safety + // preferences, reseed. Suppose `state` was fork-safe, then forked into // two children, but each of the children never fork and disable fork // safety. The children must reseed to avoid working from the same PRNG // state. @@ -430,9 +430,9 @@ rand_get_seed(state, seed, reseed_additional_data, &reseed_additional_data_len); #if defined(BORINGSSL_FIPS) - // Take a read lock around accesses to |state->drbg|. This is needed to + // Take a read lock around accesses to `state->drbg`. This is needed to // avoid returning bad entropy if we race with - // |rand_thread_state_clear_all|. + // `rand_thread_state_clear_all`. state->clear_drbg_lock.LockRead(); #endif if (!CTR_DRBG_reseed_ex(&state->drbg, seed, sizeof(seed), @@ -464,7 +464,7 @@ out += todo; out_len -= todo; // Though we only check before entering the loop, this cannot add enough to - // overflow a |size_t|. + // overflow a `size_t`. state->calls++; first_call = 0; }
diff --git a/crypto/fipsmodule/rsa/padding.cc.inc b/crypto/fipsmodule/rsa/padding.cc.inc index 44c8ce4..5d8824b 100644 --- a/crypto/fipsmodule/rsa/padding.cc.inc +++ b/crypto/fipsmodule/rsa/padding.cc.inc
@@ -184,7 +184,7 @@ if (sLen == RSA_PSS_SALTLEN_DIGEST) { sLen = (int)hLen; } else if (sLen == RSA_PSS_SALTLEN_AUTO) { - // Leave |sLen| negative, which will trigger the logic below to recover and + // Leave `sLen` negative, which will trigger the logic below to recover and // allow any salt length. } else if (sLen < 0) { // Other negative values are reserved. @@ -202,7 +202,7 @@ EM++; emLen--; } - // |sLen| may be negative for the non-standard salt length recovery mode. + // `sLen` may be negative for the non-standard salt length recovery mode. if (emLen < hLen + 2 || (sLen >= 0 && emLen < hLen + (size_t)sLen + 2)) { OPENSSL_PUT_ERROR(RSA, RSA_R_DATA_TOO_LARGE); goto err;
diff --git a/crypto/fipsmodule/rsa/rsa.cc.inc b/crypto/fipsmodule/rsa/rsa.cc.inc index 6510958..edec7ac 100644 --- a/crypto/fipsmodule/rsa/rsa.cc.inc +++ b/crypto/fipsmodule/rsa/rsa.cc.inc
@@ -407,7 +407,7 @@ int nid; // hash_len is the expected length of the hash function. uint8_t hash_len; - // len is the number of bytes of |bytes| which are valid. + // len is the number of bytes of `bytes` which are valid. uint8_t len; // bytes contains the DER bytes. uint8_t bytes[19]; @@ -551,7 +551,7 @@ if (!rsa_check_digest_size(hash_nid, digest_len)) { return 0; } - // All supported digest lengths fit in |unsigned|. + // All supported digest lengths fit in `unsigned`. assert(digest_len <= EVP_MAX_MD_SIZE); static_assert(EVP_MAX_MD_SIZE <= UINT_MAX, "digest too long"); return impl->meth->sign(hash_nid, digest, (unsigned)digest_len, out, @@ -715,8 +715,8 @@ return 1; } - // Note |bn_mul_consttime| and |bn_div_consttime| do not scale linearly, but - // checking |ainv| is in range bounds the running time, assuming |m|'s bounds + // Note `bn_mul_consttime` and `bn_div_consttime` do not scale linearly, but + // checking `ainv` is in range bounds the running time, assuming `m`'s bounds // were checked by the caller. BN_CTXScope scope(ctx); BIGNUM *tmp = BN_CTX_get(ctx); @@ -731,8 +731,8 @@ int RSA_check_key(const RSA *key) { // TODO(davidben): RSA key initialization is spread across - // |rsa_check_public_key|, |RSA_check_key|, |freeze_private_key|, and - // |BN_MONT_CTX_set_locked| as a result of API issues. See + // `rsa_check_public_key`, `RSA_check_key`, `freeze_private_key`, and + // `BN_MONT_CTX_set_locked` as a result of API issues. See // https://crbug.com/boringssl/316. As a result, we inconsistently check RSA // invariants. We should fix this and integrate that logic. @@ -746,7 +746,7 @@ return 0; } - // |impl->d| must be bounded by |impl->n|. This ensures bounds on |RSA_bits| + // `impl->d` must be bounded by `impl->n`. This ensures bounds on `RSA_bits` // translate to bounds on the running time of private key operations. if (impl->d != nullptr && (BN_is_negative(impl->d.get()) || BN_cmp(impl->d.get(), impl->n.get()) >= 0)) { @@ -777,8 +777,8 @@ BN_init(&dmq1); // Check that p * q == n. Before we multiply, we check that p and q are in - // bounds, to avoid a DoS vector in |bn_mul_consttime| below. Note that - // n was bound by |rsa_check_public_key|. This also implicitly checks p and q + // bounds, to avoid a DoS vector in `bn_mul_consttime` below. Note that + // n was bound by `rsa_check_public_key`. This also implicitly checks p and q // are odd, which is a necessary condition for Montgomery reduction. if (BN_is_negative(impl->p.get()) || constant_time_declassify_int(BN_cmp(impl->p.get(), impl->n.get()) >= 0) || @@ -833,7 +833,7 @@ pm1_bits, ctx) || !check_mod_inverse(&dmq1_ok, impl->e.get(), impl->dmq1.get(), &qm1, qm1_bits, ctx) || - // |p| is odd, so |pm1| and |p| have the same bit width. If they didn't, + // `p` is odd, so `pm1` and `p` have the same bit width. If they didn't, // we only need a lower bound anyway. !check_mod_inverse(&iqmp_ok, impl->q.get(), impl->iqmp.get(), impl->p.get(), pm1_bits, ctx)) { @@ -906,12 +906,12 @@ // Perform partial public key validation of RSA keys (SP 800-89 5.3.3). // Although this is not for primality testing, SP 800-89 cites an RSA - // primality testing algorithm, so we use |BN_prime_checks_for_generation| to + // primality testing algorithm, so we use `BN_prime_checks_for_generation` to // match. This is only a plausibility test and we expect the value to be // composite, so too few iterations will cause us to reject the key, not use // an implausible one. // - // |key->e| may be nullptr if created with |RSA_new_private_key_no_e|. + // `key->e` may be nullptr if created with `RSA_new_private_key_no_e`. enum bn_primality_result_t primality_result; auto *impl = FromOpaque(key); if (impl->e.get() == nullptr || // @@ -939,7 +939,7 @@ } // FIPS pairwise consistency test (FIPS 140-2 4.9.2). Per FIPS 140-2 IG, - // section 9.9, it is not known whether |rsa| will be used for signing or + // section 9.9, it is not known whether `rsa` will be used for signing or // encryption, so either pair-wise consistency self-test is acceptable. We // perform a signing test. uint8_t data[32] = {0};
diff --git a/crypto/fipsmodule/rsa/rsa_impl.cc.inc b/crypto/fipsmodule/rsa/rsa_impl.cc.inc index ba08ae7..2580739 100644 --- a/crypto/fipsmodule/rsa/rsa_impl.cc.inc +++ b/crypto/fipsmodule/rsa/rsa_impl.cc.inc
@@ -97,7 +97,7 @@ return 0; } - // The upper bound on |e_bits| and lower bound on |n_bits| imply e is + // The upper bound on `e_bits` and lower bound on `n_bits` imply e is // bounded by n. assert(BN_ucmp(impl->n.get(), impl->e.get()) > 0); } @@ -123,9 +123,9 @@ return 1; } -// freeze_private_key finishes initializing |rsa|'s private key components. -// After this function has returned, |rsa| may not be changed. This is needed -// because |RSA| is a public struct and, additionally, OpenSSL 1.1.0 opaquified +// freeze_private_key finishes initializing `rsa`'s private key components. +// After this function has returned, `rsa` may not be changed. This is needed +// because `RSA` is a public struct and, additionally, OpenSSL 1.1.0 opaquified // it wrong (see https://github.com/openssl/openssl/issues/5158). static int freeze_private_key(RSAImpl *rsa, BN_CTX *ctx) { rsa->lock.LockRead(); @@ -148,9 +148,9 @@ // Pre-compute various intermediate values, as well as copies of private // exponents with correct widths. Note that other threads may concurrently - // read from |rsa->n|, |rsa->e|, etc., so any fixes must be in separate - // copies. We use |mont_n->N|, |mont_p->N|, and |mont_q->N| as copies of |n|, - // |p|, and |q| with the correct minimal widths. + // read from `rsa->n`, `rsa->e`, etc., so any fixes must be in separate + // copies. We use `mont_n->N`, `mont_p->N`, and `mont_q->N` as copies of `n`, + // `p`, and `q` with the correct minimal widths. if (rsa->mont_n == nullptr) { rsa->mont_n.reset(BN_MONT_CTX_new_for_modulus(rsa->n.get(), ctx)); @@ -160,9 +160,9 @@ } n_fixed = &rsa->mont_n->N; - // The only public upper-bound of |rsa->d| is the bit length of |rsa->n|. The + // The only public upper-bound of `rsa->d` is the bit length of `rsa->n`. The // ASN.1 serialization of RSA private keys unfortunately leaks the byte length - // of |rsa->d|, but normalize it so we only leak it once, rather than per + // of `rsa->d`, but normalize it so we only leak it once, rather than per // operation. if (rsa->d != nullptr && !ensure_fixed_copy(&rsa->d_fixed, rsa->d.get(), n_fixed->width)) { @@ -201,7 +201,7 @@ return 0; } - // Compute |iqmp_mont|, which is |iqmp| in Montgomery form and with the + // Compute `iqmp_mont`, which is `iqmp` in Montgomery form and with the // correct bit width. if (rsa->iqmp_mont == nullptr) { UniquePtr<BIGNUM> iqmp_mont(BN_new()); @@ -427,18 +427,18 @@ if (impl->e == nullptr && (impl->flags & RSA_FLAG_NO_PUBLIC_EXPONENT) == 0) { // Unless the private key was specifically created with an API like - // |RSA_new_private_key_no_e|, don't allow RSA keys to be missing the public + // `RSA_new_private_key_no_e`, don't allow RSA keys to be missing the public // exponent, which disables some fault attack mitigations. (It should not be - // possible to construct such an |RSA| object in the public API.) + // possible to construct such an `RSA` object in the public API.) OPENSSL_PUT_ERROR(RSA, RSA_R_NO_PUBLIC_EXPONENT); return 0; } if (impl->p != nullptr && impl->q != nullptr && impl->e != nullptr && impl->dmp1 != nullptr && impl->dmq1 != nullptr && impl->iqmp != nullptr && - // Require that we can reduce |f| by |impl->p| and |impl->q| in constant + // Require that we can reduce `f` by `impl->p` and `impl->q` in constant // time, which requires primes be the same size, rounded to the Montgomery - // coefficient. (See |mod_montgomery|.) This is not required by RFC 8017, + // coefficient. (See `mod_montgomery`.) This is not required by RFC 8017, // but it is true for keys generated by us and all common implementations. bn_less_than_montgomery_R(impl->q.get(), impl->mont_p.get()) && bn_less_than_montgomery_R(impl->p.get(), impl->mont_q.get())) { @@ -459,8 +459,8 @@ // works when the CRT isn't used. That attack is much less likely to succeed // than the CRT attack, but there have likely been improvements since 1997. // - // This check is cheap assuming |e| is small, which we require in - // |rsa_check_public_key|. + // This check is cheap assuming `e` is small, which we require in + // `rsa_check_public_key`. if (impl->e != nullptr) { BIGNUM *vrfy = BN_CTX_get(ctx.get()); if (vrfy == nullptr || @@ -472,7 +472,7 @@ } } - // The computation should have left |result| as a maximally-wide number, so + // The computation should have left `result` as a maximally-wide number, so // that it and serializing does not leak information about the magnitude of // the result. // @@ -487,8 +487,8 @@ return 1; } -// mod_montgomery sets |r| to |I| mod |p|. |I| must already be fully reduced -// modulo |p| times |q|. It returns one on success and zero on error. +// mod_montgomery sets `r` to `I` mod `p`. `I` must already be fully reduced +// modulo `p` times `q`. It returns one on success and zero on error. static int mod_montgomery(BIGNUM *r, const BIGNUM *I, const BIGNUM *p, const BN_MONT_CTX *mont_p, const BIGNUM *q, BN_CTX *ctx) { @@ -508,13 +508,13 @@ return 0; } - // By precomputing R^3 mod p (normally |BN_MONT_CTX| only uses R^2 mod p) and - // adjusting the API for |BN_mod_exp_mont_consttime|, we could instead compute + // By precomputing R^3 mod p (normally `BN_MONT_CTX` only uses R^2 mod p) and + // adjusting the API for `BN_mod_exp_mont_consttime`, we could instead compute // I * R mod p here and save a reduction per prime. But this would require // changing the RSAZ code and may not be worth it. Note that the RSAZ code // uses a different radix, so it uses R' = 2^1044. There we'd actually want // R^2 * R', and would further benefit from a precomputed R'^2. It currently - // converts |mont_p->RR| to R'^2. + // converts `mont_p->RR` to R'^2. return 1; } @@ -538,49 +538,49 @@ return 0; } - // Use the minimal-width versions of |n|, |p|, and |q|. Either works, but if + // Use the minimal-width versions of `n`, `p`, and `q`. Either works, but if // someone gives us non-minimal values, these will be slightly more efficient // on the non-Montgomery operations. BIGNUM *n = &rsa->mont_n->N; BIGNUM *p = &rsa->mont_p->N; BIGNUM *q = &rsa->mont_q->N; - // This is a pre-condition for |mod_montgomery|. It was already checked by the + // This is a pre-condition for `mod_montgomery`. It was already checked by the // caller. declassify_assert(BN_ucmp(I, n) < 0); - if ( // |m1| is the result modulo |q|. + if ( // `m1` is the result modulo `q`. !mod_montgomery(r1, I, q, rsa->mont_q.get(), p, ctx) || !BN_mod_exp_mont_consttime(m1, r1, rsa->dmq1_fixed.get(), q, ctx, rsa->mont_q.get()) || - // |r0| is the result modulo |p|. + // `r0` is the result modulo `p`. !mod_montgomery(r1, I, p, rsa->mont_p.get(), q, ctx) || !BN_mod_exp_mont_consttime(r0, r1, rsa->dmp1_fixed.get(), p, ctx, rsa->mont_p.get()) || - // Compute r0 = r0 - m1 mod p. |m1| is reduced mod |q|, not |p|, so we - // just run |mod_montgomery| again for srsaicity. This could be more - // efficient with more cases: if |p > q|, |m1| is already reduced. If - // |p < q| but they have the same bit width, |bn_reduce_once| suffices. + // Compute r0 = r0 - m1 mod p. `m1` is reduced mod `q`, not `p`, so we + // just run `mod_montgomery` again for srsaicity. This could be more + // efficient with more cases: if `p > q`, `m1` is already reduced. If + // `p < q` but they have the same bit width, `bn_reduce_once` suffices. // However, compared to over 2048 Montgomery multiplications above, this // difference is not measurable. !mod_montgomery(r1, m1, p, rsa->mont_p.get(), q, ctx) || !bn_mod_sub_consttime(r0, r0, r1, p, ctx) || // r0 = r0 * iqmp mod p. We use Montgomery multiplication to compute this - // in constant time. |iqmp_mont| is in Montgomery form and r0 is not, so + // in constant time. `iqmp_mont` is in Montgomery form and r0 is not, so // the result is taken out of Montgomery form. !BN_mod_mul_montgomery(r0, r0, rsa->iqmp_mont.get(), rsa->mont_p.get(), ctx) || // r0 = r0 * q + m1 gives the final result. Reducing modulo q gives m1, so // it is correct mod p. Reducing modulo p gives (r0-m1)*iqmp*q + m1 = r0, // so it is correct mod q. Finally, the result is bounded by [m1, n + m1), - // and the result is at least |m1|, so this must be the unique answer in + // and the result is at least `m1`, so this must be the unique answer in // [0, n). !bn_mul_consttime(r0, r0, q, ctx) || // !bn_uadd_consttime(r0, r0, m1)) { return 0; } - // The result should be bounded by |n|, but fixed-width operations may + // The result should be bounded by `n`, but fixed-width operations may // bound the width slightly higher, so fix it. This trips constant-time checks // because a naive data flow analysis does not realize the excess words are // publicly zero. @@ -600,9 +600,9 @@ return *out != nullptr; } -// generate_prime sets |out| to a prime with length |bits| such that |out|-1 is -// relatively prime to |e|. If |p| is non-NULL, |out| will also not be close to -// |p|. |pow2_bits_100| must be 2^(bits-100). +// generate_prime sets `out` to a prime with length `bits` such that `out`-1 is +// relatively prime to `e`. If `p` is non-NULL, `out` will also not be close to +// `p`. `pow2_bits_100` must be 2^(bits-100). // // This function fails with probability around 2^-21. static int generate_prime(BIGNUM *out, int bits, const BIGNUM *e, @@ -615,14 +615,14 @@ assert(BN_is_pow2(pow2_bits_100)); assert(BN_is_bit_set(pow2_bits_100, bits - 100)); - // See FIPS 186-5 appendix A.1.3, steps 4 and 5. Note |bits| here is nlen/2. + // See FIPS 186-5 appendix A.1.3, steps 4 and 5. Note `bits` here is nlen/2. - // Use the limit from steps 4.7 and 5.8 for most values of |e|. When |e| is 3, + // Use the limit from steps 4.7 and 5.8 for most values of `e`. When `e` is 3, // the 186-5 limit is too low, so we use a higher one. Note this case is not - // reachable from |RSA_generate_key_fips|. + // reachable from `RSA_generate_key_fips`. // - // |limit| determines the failure probability. We must find a prime that is - // not 1 mod |e|. By the prime number theorem, we'll find one with probability + // `limit` determines the failure probability. We must find a prime that is + // not 1 mod `e`. By the prime number theorem, we'll find one with probability // p = (e-1)/e * 2/(ln(2)*bits). Note the second term is doubled because we // discard even numbers. // @@ -659,7 +659,7 @@ } for (;;) { - // Generate a random number of length |bits| where the bottom bit is set and + // Generate a random number of length `bits` where the bottom bit is set and // top two bits are set (steps 4.2–4.4 and 5.2–5.4): // // - Setting the top two bits is permitted by steps 4.2.1 and 5.2.1. Doing @@ -673,7 +673,7 @@ } if (p != nullptr) { - // If |p| and |out| are too close, try again (step 5.5). + // If `p` and `out` are too close, try again (step 5.5). if (!bn_abs_sub_consttime(tmp, out, p, ctx)) { return 0; } @@ -694,7 +694,7 @@ return 0; } if (constant_time_declassify_int(relatively_prime)) { - // Test |out| for primality (steps 4.5.1 and 5.6.1). + // Test `out` for primality (steps 4.5.1 and 5.6.1). int is_probable_prime; if (!BN_primality_test(&is_probable_prime, out, BN_prime_checks_for_generation, ctx, 0, cb)) { @@ -719,7 +719,7 @@ } // rsa_generate_key_impl generates an RSA key using a generalized version of -// FIPS 186-5 appendix A.1.3. |RSA_generate_key_fips| performs additional checks +// FIPS 186-5 appendix A.1.3. `RSA_generate_key_fips` performs additional checks // for FIPS-compliant key generation. // // This function returns one on success and zero on failure. It has a failure @@ -731,7 +731,7 @@ return 0; } - // Always generate RSA keys which are a multiple of 128 bits. Round |bits| + // Always generate RSA keys which are a multiple of 128 bits. Round `bits` // down as needed. bits &= ~127; @@ -743,7 +743,7 @@ // Reject excessively large public exponents. Windows CryptoAPI and Go don't // support values larger than 32 bits, so match their limits for generating - // keys. (|rsa_check_public_key| uses a slightly more conservative value, but + // keys. (`rsa_check_public_key` uses a slightly more conservative value, but // we don't need to support generating such keys.) // https://github.com/golang/go/issues/3161 // https://msdn.microsoft.com/en-us/library/aa387685(VS.85).aspx @@ -756,13 +756,13 @@ // Catching these here prevents endless loops or slow computation when trying // to generate keys later, and results in a better error code. if ( - // Would fail in |bn_lcm_consttime| as it only allows positive integers. + // Would fail in `bn_lcm_consttime` as it only allows positive integers. BN_is_negative(e_value) || - // Would fail in |generate_prime| as only one |rsa->p|-1 is coprime with - // an even |e_value| and that one is a little bit short. (The R in RSA + // Would fail in `generate_prime` as only one `rsa->p`-1 is coprime with + // an even `e_value` and that one is a little bit short. (The R in RSA // doesn't stand for Rabin.) !BN_is_odd(e_value) || - // Would loop endlessly because it'll always compute an |rsa->d| exponent + // Would loop endlessly because it'll always compute an `rsa->d` exponent // of 1, which is too small. BN_is_one(e_value)) { OPENSSL_PUT_ERROR(RSA, RSA_R_BAD_E_VALUE); @@ -809,10 +809,10 @@ } do { - // Generate p and q, each of size |prime_bits|, using the steps outlined in + // Generate p and q, each of size `prime_bits`, using the steps outlined in // appendix FIPS 186-5 appendix C.3.3. // - // Each call to |generate_prime| fails with probability p = 2^-21. The + // Each call to `generate_prime` fails with probability p = 2^-21. The // probability that either call fails is 1 - (1-p)^2, which is around 2^-20. if (!generate_prime(rsa->p.get(), prime_bits, rsa->e.get(), nullptr, pow2_prime_bits_100, ctx.get(), cb) || @@ -845,7 +845,7 @@ return 0; } - // Retry if |rsa->d| <= 2^|prime_bits|. See appendix A.3.1's guidance on + // Retry if `rsa->d` <= 2^`prime_bits`. See appendix A.3.1's guidance on // values for d. When we retry, p and q are discarded, so it is safe to leak // this comparison. } while ( @@ -866,7 +866,7 @@ } bn_set_minimal_width(rsa->n.get()); - // |rsa->n| is computed from the private key, but is public. + // `rsa->n` is computed from the private key, but is public. bn_declassify(rsa->n.get()); // Calculate q^-1 mod p. @@ -878,8 +878,8 @@ return 0; } - // Sanity-check that |rsa->n| has the specified size. This is rsaied by - // |generate_prime|'s bounds. + // Sanity-check that `rsa->n` has the specified size. This is rsaied by + // `generate_prime`'s bounds. if (BN_num_bits(rsa->n.get()) != (unsigned)bits) { OPENSSL_PUT_ERROR(RSA, ERR_R_INTERNAL_ERROR); return 0; @@ -887,7 +887,7 @@ // The key generation process is complex and thus error-prone. It could be // disastrous to generate and then use a bad key so double-check that the key - // makes sense. Also, while |rsa| is mutable, fill in the cached components. + // makes sense. Also, while `rsa` is mutable, fill in the cached components. if (!RSA_check_key(rsa) || !freeze_private_key(rsa, ctx.get())) { OPENSSL_PUT_ERROR(RSA, RSA_R_INTERNAL_ERROR); return 0; @@ -909,7 +909,7 @@ UniquePtr<RSAImpl> tmp; - // |rsa_generate_key_impl|'s 2^-20 failure probability is too high at scale, + // `rsa_generate_key_impl`'s 2^-20 failure probability is too high at scale, // so we run the FIPS algorithm four times, bringing it down to 2^-80. We // should just adjust the retry limit, but FIPS 186-5 prescribes that value // and thus results in unnecessary complexity. @@ -929,8 +929,8 @@ tmp = nullptr; failures++; - // Only retry on |RSA_R_TOO_MANY_ITERATIONS|. This is so a caller-induced - // failure in |BN_GENCB_call| is still fatal. + // Only retry on `RSA_R_TOO_MANY_ITERATIONS`. This is so a caller-induced + // failure in `BN_GENCB_call` is still fatal. } while (failures < 4 && ERR_equals(ERR_peek_error(), ERR_LIB_RSA, RSA_R_TOO_MANY_ITERATIONS)); @@ -992,7 +992,7 @@ DEFINE_METHOD_FUNCTION(RSA_METHOD, RSA_default_method) { // All of the methods are NULL to make it easier for the compiler/linker to // drop unused functions. The wrapper functions will select the appropriate - // |rsa_default_*| implementation. + // `rsa_default_*` implementation. OPENSSL_memset(out, 0, sizeof(RSA_METHOD)); out->common.is_static = 1; }
diff --git a/crypto/fipsmodule/self_check/fips.cc.inc b/crypto/fipsmodule/self_check/fips.cc.inc index 5ed05cb..e2eaf70 100644 --- a/crypto/fipsmodule/self_check/fips.cc.inc +++ b/crypto/fipsmodule/self_check/fips.cc.inc
@@ -111,7 +111,7 @@ if (!CRYPTO_set_thread_local(OPENSSL_THREAD_LOCAL_FIPS_COUNTERS, array, OPENSSL_free)) { - // |OPENSSL_free| has already been called by |CRYPTO_set_thread_local|. + // `OPENSSL_free` has already been called by `CRYPTO_set_thread_local`. return; } }
diff --git a/crypto/fipsmodule/self_check/self_check.cc.inc b/crypto/fipsmodule/self_check/self_check.cc.inc index 8ea40a1..d54e45f 100644 --- a/crypto/fipsmodule/self_check/self_check.cc.inc +++ b/crypto/fipsmodule/self_check/self_check.cc.inc
@@ -297,7 +297,7 @@ // // Self tests that are slow are deferred until the corresponding algorithm is // actually exercised, in FIPS mode. (In non-FIPS mode these tests are only run -// when requested by |BORINGSSL_self_test|.) +// when requested by `BORINGSSL_self_test`.) static int boringssl_self_test_rsa_sign() { UniquePtr<RSA> rsa_key(self_test_rsa_private_key()); @@ -484,7 +484,7 @@ 0xa5, 0x2c, 0xb5, 0x9f, 0xeb, 0x70, 0xae, 0xde, 0x6c, 0xe3, 0xbf, 0xb3, 0xe0, 0x10, 0x54, 0x85, 0xab, 0xd8, 0x61, 0xd7, 0x7b, }; - // kP256PointResult is |kP256Scalar|×|kP256Point|. + // kP256PointResult is `kP256Scalar`×`kP256Point`. static const uint8_t kP256PointResult[65] = { 0x04, 0xf1, 0x63, 0x00, 0x88, 0xc5, 0xd5, 0xe9, 0x05, 0x52, 0xac, 0xb6, 0xec, 0x68, 0x76, 0xb8, 0x73, 0x7f, 0x0f, 0x72, 0x34, 0xe6,
diff --git a/crypto/fipsmodule/service_indicator/service_indicator.cc.inc b/crypto/fipsmodule/service_indicator/service_indicator.cc.inc index ef8fb35..20b2b0c 100644 --- a/crypto/fipsmodule/service_indicator/service_indicator.cc.inc +++ b/crypto/fipsmodule/service_indicator/service_indicator.cc.inc
@@ -34,14 +34,14 @@ // state of the FIPS service indicator. struct fips_service_indicator_state { // lock_state records the number of times the indicator has been locked. - // When it is zero (i.e. |STATE_UNLOCKED|) then the indicator can be updated. + // When it is zero (i.e. `STATE_UNLOCKED`) then the indicator can be updated. uint64_t lock_state; // counter is the indicator state. It is incremented when an approved service // completes. uint64_t counter; }; -// service_indicator_get returns a pointer to the |fips_service_indicator_state| +// service_indicator_get returns a pointer to the `fips_service_indicator_state` // for the current thread. It returns nullptr on error. // // FIPS 140-3 requires that the module should provide the service indicator @@ -101,15 +101,15 @@ return; } - // |FIPS_service_indicator_lock_state| and - // |FIPS_service_indicator_unlock_state| should not under/overflow in normal + // `FIPS_service_indicator_lock_state` and + // `FIPS_service_indicator_unlock_state` should not under/overflow in normal // operation. They are still checked and errors added to facilitate testing in // service_indicator_test.cc. This should only happen if lock/unlock are // called in an incorrect order or multiple times in the same function. const uint64_t new_state = indicator->lock_state + 1; if (new_state < indicator->lock_state) { // Overflow. This would imply that our call stack length has exceeded a - // |uint64_t| which impossible on a 64-bit system. + // `uint64_t` which impossible on a 64-bit system. abort(); } @@ -201,8 +201,8 @@ // EVP_PKEY_RSA_PSS SPKIs aren't supported. if (pkey_type == EVP_PKEY_RSA) { // Message digest used in the private key should be of the same type - // as the given one, so we extract the MD type from the |EVP_PKEY| - // and compare it with the type in |ctx|. + // as the given one, so we extract the MD type from the `EVP_PKEY` + // and compare it with the type in `ctx`. const EVP_MD *pctx_md; if (!EVP_PKEY_CTX_get_signature_md(pctx, &pctx_md)) { goto err; @@ -230,7 +230,7 @@ } // The approved RSA key sizes for signing are 2048, 3072 and 4096 bits. - // Note: |EVP_PKEY_size| returns the size in bytes. + // Note: `EVP_PKEY_size` returns the size in bytes. size_t pkey_size = EVP_PKEY_size(FromOpaque(ctx->pctx)->pkey.get()); // Check if the MD type and the RSA key size are approved. @@ -322,7 +322,7 @@ uint64_t bssl::FIPS_service_indicator_after_call() { // One is returned so that the return value is always greater than zero, the - // return value of |FIPS_service_indicator_before_call|. This makes everything + // return value of `FIPS_service_indicator_before_call`. This makes everything // report as "approved" in non-FIPS builds. return 1; }
diff --git a/crypto/fipsmodule/sha/sha256.cc.inc b/crypto/fipsmodule/sha/sha256.cc.inc index 20cfda9..8a179fd 100644 --- a/crypto/fipsmodule/sha/sha256.cc.inc +++ b/crypto/fipsmodule/sha/sha256.cc.inc
@@ -106,9 +106,9 @@ bcm_infallible bssl::BCM_sha256_final(uint8_t out[SHA256_DIGEST_LENGTH], SHA256_CTX *c) { - // Ideally we would assert |sha->md_len| is |SHA256_DIGEST_LENGTH| tomatch the - // size hint, but calling code often pairs |SHA224_Init| with |SHA256_Final| - // and expects |sha->md_len| to carry the size over. + // Ideally we would assert `sha->md_len` is `SHA256_DIGEST_LENGTH` tomatch the + // size hint, but calling code often pairs `SHA224_Init` with `SHA256_Final` + // and expects `sha->md_len` to carry the size over. // // TODO(davidben): Add an assert and fix code to match them up. sha256_final_impl(out, c->md_len, c); @@ -117,8 +117,8 @@ bcm_infallible bssl::BCM_sha224_final(uint8_t out[SHA224_DIGEST_LENGTH], SHA256_CTX *ctx) { - // This function must be paired with |SHA224_Init|, which sets |ctx->md_len| - // to |SHA224_DIGEST_LENGTH|. + // This function must be paired with `SHA224_Init`, which sets `ctx->md_len` + // to `SHA224_DIGEST_LENGTH`. assert(ctx->md_len == SHA224_DIGEST_LENGTH); sha256_final_impl(out, SHA224_DIGEST_LENGTH, ctx); return bcm_infallible::approved;
diff --git a/crypto/fipsmodule/sha/sha512.cc.inc b/crypto/fipsmodule/sha/sha512.cc.inc index f2282f4..164a80e 100644 --- a/crypto/fipsmodule/sha/sha512.cc.inc +++ b/crypto/fipsmodule/sha/sha512.cc.inc
@@ -92,8 +92,8 @@ bcm_infallible bssl::BCM_sha384_final(uint8_t out[SHA384_DIGEST_LENGTH], SHA512_CTX *sha) { - // This function must be paired with |BCM_sha384_init|, which sets - // |sha->md_len| to |SHA384_DIGEST_LENGTH|. + // This function must be paired with `BCM_sha384_init`, which sets + // `sha->md_len` to `SHA384_DIGEST_LENGTH`. assert(sha->md_len == SHA384_DIGEST_LENGTH); sha512_final_impl(out, SHA384_DIGEST_LENGTH, sha); return bcm_infallible::approved; @@ -111,8 +111,8 @@ bcm_infallible bssl::BCM_sha512_256_final(uint8_t out[SHA512_256_DIGEST_LENGTH], SHA512_CTX *sha) { - // This function must be paired with |BCM_sha512_256_init|, which sets - // |sha->md_len| to |SHA512_256_DIGEST_LENGTH|. + // This function must be paired with `BCM_sha512_256_init`, which sets + // `sha->md_len` to `SHA512_256_DIGEST_LENGTH`. assert(sha->md_len == SHA512_256_DIGEST_LENGTH); sha512_final_impl(out, SHA512_256_DIGEST_LENGTH, sha); return bcm_infallible::approved; @@ -170,9 +170,9 @@ bcm_infallible bssl::BCM_sha512_final(uint8_t out[SHA512_DIGEST_LENGTH], SHA512_CTX *sha) { - // Ideally we would assert |sha->md_len| is |SHA512_DIGEST_LENGTH| to match - // the size hint, but calling code often pairs |BCM_sha384_init| with - // |BCM_sha512_final| and expects |sha->md_len| to carry the size over. + // Ideally we would assert `sha->md_len` is `SHA512_DIGEST_LENGTH` to match + // the size hint, but calling code often pairs `BCM_sha384_init` with + // `BCM_sha512_final` and expects `sha->md_len` to carry the size over. // // TODO(davidben): Add an assert and fix code to match them up. sha512_final_impl(out, sha->md_len, sha);
diff --git a/crypto/fipsmodule/tls/kdf.cc.inc b/crypto/fipsmodule/tls/kdf.cc.inc index 2446a36..350cd06 100644 --- a/crypto/fipsmodule/tls/kdf.cc.inc +++ b/crypto/fipsmodule/tls/kdf.cc.inc
@@ -29,8 +29,8 @@ using namespace bssl; // tls1_P_hash computes the TLS P_<hash> function as described in RFC 5246, -// section 5. It XORs |out_len| bytes to |out|, using |md| as the hash and -// |secret| as the secret. |label|, |seed1|, and |seed2| are concatenated to +// section 5. It XORs `out_len` bytes to `out`, using `md` as the hash and +// `secret` as the secret. `label`, `seed1`, and `seed2` are concatenated to // form the seed parameter. It returns true on success and false on failure. static int tls1_P_hash(uint8_t *out, size_t out_len, const EVP_MD *md, const uint8_t *secret, size_t secret_len, @@ -60,7 +60,7 @@ unsigned len_u; uint8_t hmac[EVP_MAX_MD_SIZE]; if (!HMAC_CTX_copy_ex(&ctx, &ctx_init) || !HMAC_Update(&ctx, A1, A1_len) || - // Save a copy of |ctx| to compute the next A1 value below. + // Save a copy of `ctx` to compute the next A1 value below. (out_len > chunk && !HMAC_CTX_copy_ex(&ctx_tmp, &ctx)) || !HMAC_Update(&ctx, (const uint8_t *)label, label_len) || !HMAC_Update(&ctx, seed1, seed1_len) || @@ -71,7 +71,7 @@ size_t len = len_u; assert(len == chunk); - // XOR the result into |out|. + // XOR the result into `out`. if (len > out_len) { len = out_len; } @@ -117,14 +117,14 @@ int ret = 0; if (digest == EVP_md5_sha1()) { - // If using the MD5/SHA1 PRF, |secret| is partitioned between MD5 and SHA-1. + // If using the MD5/SHA1 PRF, `secret` is partitioned between MD5 and SHA-1. size_t secret_half = secret_len - (secret_len / 2); if (!tls1_P_hash(out, out_len, EVP_md5(), secret, secret_half, label, label_len, seed1, seed1_len, seed2, seed2_len)) { goto end; } - // Note that, if |secret_len| is odd, the two halves share a byte. + // Note that, if `secret_len` is odd, the two halves share a byte. secret += secret_len - secret_half; secret_len = secret_half; digest = EVP_sha1();