Documentation: Change |...| to `...` for code references in comments 8/N This CL includes the result of running util/update_comment_style.py over all *.h files in crypto/, and fixing omissions manually if necessary. Bug: 42290410 Change-Id: I6f0a5257a1a23305b34dc69dca7f29456a6a6964 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/96113 Presubmit-BoringSSL-Verified: boringssl-scoped@luci-project-accounts.iam.gserviceaccount.com <boringssl-scoped@luci-project-accounts.iam.gserviceaccount.com> Reviewed-by: Rudolf Polzer <rpolzer@google.com> Commit-Queue: Lily Chen <chlily@google.com>
diff --git a/crypto/asn1/internal.h b/crypto/asn1/internal.h index 970de10..6013057 100644 --- a/crypto/asn1/internal.h +++ b/crypto/asn1/internal.h
@@ -25,22 +25,22 @@ // Wrapper functions for time functions. -// OPENSSL_gmtime converts a time_t value in |time| which must be in the range -// of year 0000 to 9999 to a broken out time value in |tm|. On success |tm| is +// OPENSSL_gmtime converts a time_t value in `time` which must be in the range +// of year 0000 to 9999 to a broken out time value in `tm`. On success `tm` is // returned. On failure NULL is returned. OPENSSL_EXPORT struct tm *OPENSSL_gmtime(const time_t *time, struct tm *result); -// OPENSSL_gmtime_adj returns one on success, and updates |tm| by adding -// |offset_day| days and |offset_sec| seconds. It returns zero on failure. |tm| +// OPENSSL_gmtime_adj returns one on success, and updates `tm` by adding +// `offset_day` days and `offset_sec` seconds. It returns zero on failure. `tm` // must be in the range of year 0000 to 9999 both before and after the update or // a failure will be returned. OPENSSL_EXPORT int OPENSSL_gmtime_adj(struct tm *tm, int offset_day, int64_t offset_sec); -// OPENSSL_gmtime_diff calculates the difference between |from| and |to|. It +// OPENSSL_gmtime_diff calculates the difference between `from` and `to`. It // returns one, and outputs the difference as a number of days and seconds in -// |*out_days| and |*out_secs| on success. It returns zero on failure. Both -// |from| and |to| must be in the range of year 0000 to 9999 or a failure will +// `*out_days` and `*out_secs` on success. It returns zero on failure. Both +// `from` and `to` must be in the range of year 0000 to 9999 or a failure will // be returned. OPENSSL_EXPORT int OPENSSL_gmtime_diff(int *out_days, int *out_secs, const struct tm *from, @@ -57,10 +57,10 @@ BSSL_NAMESPACE_END -// An asn1_object_st (aka |ASN1_OBJECT|) represents an ASN.1 OBJECT IDENTIFIER. -// Note: Mutating an |ASN1_OBJECT| is only permitted when initializing it. The -// library maintains a table of static |ASN1_OBJECT|s, which may be referenced -// by non-const |ASN1_OBJECT| pointers. Code which receives an |ASN1_OBJECT| +// An asn1_object_st (aka `ASN1_OBJECT`) represents an ASN.1 OBJECT IDENTIFIER. +// Note: Mutating an `ASN1_OBJECT` is only permitted when initializing it. The +// library maintains a table of static `ASN1_OBJECT`s, which may be referenced +// by non-const `ASN1_OBJECT` pointers. Code which receives an `ASN1_OBJECT` // pointer externally must assume it is immutable, even if the pointer is not // const. struct asn1_object_st { @@ -75,40 +75,40 @@ ASN1_OBJECT *ASN1_OBJECT_new(); -// asn1_parse_object parses a DER-encoded ASN.1 OBJECT IDENTIFIER from |cbs| and -// write the result to |out|. If |tag| is non-zero, the value is implicitly -// tagged with |tag|. On success, it returns a newly-allocated |ASN1_OBJECT| -// with the result and advances |cbs| past the parsed element. +// asn1_parse_object parses a DER-encoded ASN.1 OBJECT IDENTIFIER from `cbs` and +// write the result to `out`. If `tag` is non-zero, the value is implicitly +// tagged with `tag`. On success, it returns a newly-allocated `ASN1_OBJECT` +// with the result and advances `cbs` past the parsed element. // // TODO(crbug.com/boringssl/414361735): This should return a bssl::UniquePtr, // but cannot until it is made C++ linkage. ASN1_OBJECT *asn1_parse_object(CBS *cbs, CBS_ASN1_TAG tag); -// asn1_marshal_object marshals |in| as a DER-encoded, ASN.1 OBJECT IDENTIFIER -// and writes the result to |out|. It returns one on success and zero on error. -// If |tag| is non-zero, the tag is replaced with |tag|. +// asn1_marshal_object marshals `in` as a DER-encoded, ASN.1 OBJECT IDENTIFIER +// and writes the result to `out`. It returns one on success and zero on error. +// If `tag` is non-zero, the tag is replaced with `tag`. int asn1_marshal_object(CBB *out, const ASN1_OBJECT *in, CBS_ASN1_TAG tag); // Strings. -// asn1_is_printable returns one if |value| is a valid Unicode codepoint for an +// asn1_is_printable returns one if `value` is a valid Unicode codepoint for an // ASN.1 PrintableString, and zero otherwise. int asn1_is_printable(uint32_t value); -// asn1_string_init initializes |str|, which may be uninitialized, with type -// |type|. +// asn1_string_init initializes `str`, which may be uninitialized, with type +// `type`. void asn1_string_init(ASN1_STRING *str, int type); -// asn1_string_cleanup releases memory associated with |str|'s value, without -// freeing |str| itself. +// asn1_string_cleanup releases memory associated with `str`'s value, without +// freeing `str` itself. void asn1_string_cleanup(ASN1_STRING *str); // The following functions parse a DER-encoded ASN.1 value of the specified -// type from |cbs| and write the result to |*out|. If |tag| is non-zero, the -// value is implicitly tagged with |tag|. On success, they return one and -// advance |cbs| past the parsed element. On entry, |*out| must contain an -// |ASN1_STRING| in some valid state. +// type from `cbs` and write the result to `*out`. If `tag` is non-zero, the +// value is implicitly tagged with `tag`. On success, they return one and +// advance `cbs` past the parsed element. On entry, `*out` must contain an +// `ASN1_STRING` in some valid state. int asn1_parse_bit_string(CBS *cbs, ASN1_BIT_STRING *out, CBS_ASN1_TAG tag); int asn1_parse_integer(CBS *cbs, ASN1_INTEGER *out, CBS_ASN1_TAG tag); int asn1_parse_enumerated(CBS *cbs, ASN1_ENUMERATED *out, CBS_ASN1_TAG tag); @@ -123,25 +123,25 @@ int asn1_parse_utc_time(CBS *cbs, ASN1_UTCTIME *out, CBS_ASN1_TAG tag, int allow_timezone_offset); -// asn1_parse_bit_string_with_bad_length behaves like |asn1_parse_bit_string| +// asn1_parse_bit_string_with_bad_length behaves like `asn1_parse_bit_string` // but tolerates BER non-minimal, definite lengths. int asn1_parse_bit_string_with_bad_length(CBS *cbs, ASN1_BIT_STRING *out); -// asn1_marshal_bit_string marshals |in| as a DER-encoded, ASN.1 BIT STRING and -// writes the result to |out|. It returns one on success and zero on error. If -// |tag| is non-zero, the tag is replaced with |tag|. +// asn1_marshal_bit_string marshals `in` as a DER-encoded, ASN.1 BIT STRING and +// writes the result to `out`. It returns one on success and zero on error. If +// `tag` is non-zero, the tag is replaced with `tag`. int asn1_marshal_bit_string(CBB *out, const ASN1_BIT_STRING *in, CBS_ASN1_TAG tag); -// asn1_marshal_integer marshals |in| as a DER-encoded, ASN.1 INTEGER and writes -// the result to |out|. It returns one on success and zero on error. If |tag| is -// non-zero, the tag is replaced with |tag|. This can also be used to marshal an +// asn1_marshal_integer marshals `in` as a DER-encoded, ASN.1 INTEGER and writes +// the result to `out`. It returns one on success and zero on error. If `tag` is +// non-zero, the tag is replaced with `tag`. This can also be used to marshal an // ASN.1 ENUMERATED value by overriding the tag. int asn1_marshal_integer(CBB *out, const ASN1_INTEGER *in, CBS_ASN1_TAG tag); -// asn1_marshal_octet_string marshals |in| as a DER-encoded, ASN.1 OCTET STRING -// and writes the result to |out|. It returns one on success and zero on error. -// If |tag| is non-zero, the tag is replaced with |tag|. +// asn1_marshal_octet_string marshals `in` as a DER-encoded, ASN.1 OCTET STRING +// and writes the result to `out`. It returns one on success and zero on error. +// If `tag` is non-zero, the tag is replaced with `tag`. // // This function may be used to marshal other string-based universal types whose // encoding is that of an implicitly-tagged OCTET STRING, e.g. UTF8String. @@ -159,37 +159,37 @@ // The ASN.1 ANY type. -// asn1_type_value_as_pointer returns |a|'s value in pointer form. This is +// asn1_type_value_as_pointer returns `a`'s value in pointer form. This is // usually the value object but, for BOOLEAN values, is 0 or 0xff cast to // a pointer. const void *asn1_type_value_as_pointer(const ASN1_TYPE *a); -// asn1_type_set0_string sets |a|'s value to the object represented by |str| and -// takes ownership of |str|. +// asn1_type_set0_string sets `a`'s value to the object represented by `str` and +// takes ownership of `str`. void asn1_type_set0_string(ASN1_TYPE *a, ASN1_STRING *str); -// asn1_type_cleanup releases memory associated with |a|'s value, without -// freeing |a| itself. +// asn1_type_cleanup releases memory associated with `a`'s value, without +// freeing `a` itself. void asn1_type_cleanup(ASN1_TYPE *a); -// asn1_parse_any parses a DER-encoded ASN.1 value of any type from |cbs| and -// writes the result to |*out|. On success, it advances |cbs| past the parsed -// element and returns one. On entry, |*out| must contain an |ASN1_TYPE| in some +// asn1_parse_any parses a DER-encoded ASN.1 value of any type from `cbs` and +// writes the result to `*out`. On success, it advances `cbs` past the parsed +// element and returns one. On entry, `*out` must contain an `ASN1_TYPE` in some // valid state. int asn1_parse_any(CBS *cbs, ASN1_TYPE *out); -// asn1_parse_any_as_string behaves like |asn1_parse_any| but represents the -// value as an |ASN1_STRING|. Types which are not represented with -// |ASN1_STRING|, such as |ASN1_OBJECT|, are represented with type -// |V_ASN1_OTHER|. +// asn1_parse_any_as_string behaves like `asn1_parse_any` but represents the +// value as an `ASN1_STRING`. Types which are not represented with +// `ASN1_STRING`, such as `ASN1_OBJECT`, are represented with type +// `V_ASN1_OTHER`. int asn1_parse_any_as_string(CBS *cbs, ASN1_STRING *out); -// asn1_marshal_any marshals |in| as a DER-encoded ASN.1 value and writes the -// result to |out|. It returns one on success and zeron on error. +// asn1_marshal_any marshals `in` as a DER-encoded ASN.1 value and writes the +// result to `out`. It returns one on success and zeron on error. int asn1_marshal_any(CBB *out, const ASN1_TYPE *in); -// asn1_marshal_any_string marshals |in| as a DER-encoded ASN.1 value and writes -// the result to |out|. It returns one on success and zeron on error. +// asn1_marshal_any_string marshals `in` as a DER-encoded ASN.1 value and writes +// the result to `out`. It returns one on success and zeron on error. int asn1_marshal_any_string(CBB *out, const ASN1_STRING *in); @@ -198,9 +198,9 @@ // ASN1_ENCODING is used to save the received encoding of an ASN.1 type. This // avoids problems with invalid encodings that break signatures. typedef struct ASN1_ENCODING_st { - // enc is the saved DER encoding. Its ownership is determined by |buf|. + // enc is the saved DER encoding. Its ownership is determined by `buf`. uint8_t *enc; - // len is the length of |enc|. If zero, there is no saved encoding. + // len is the length of `enc`. If zero, there is no saved encoding. size_t len; } ASN1_ENCODING; @@ -209,40 +209,40 @@ void ASN1_template_free(ASN1_VALUE **pval, const ASN1_TEMPLATE *tt); -// ASN1_item_ex_d2i parses |len| bytes from |*in| as a structure of type |it| -// and writes the result to |*pval|. If |tag| is non-negative, |it| is -// implicitly tagged with the tag specified by |tag| and |aclass|. If |opt| is +// ASN1_item_ex_d2i parses `len` bytes from `*in` as a structure of type `it` +// and writes the result to `*pval`. If `tag` is non-negative, `it` is +// implicitly tagged with the tag specified by `tag` and `aclass`. If `opt` is // non-zero, the value is optional. // -// This function returns one and advances |*in| if an object was successfully +// This function returns one and advances `*in` if an object was successfully // parsed, -1 if an optional value was successfully skipped, and zero on error. int ASN1_item_ex_d2i(ASN1_VALUE **pval, const unsigned char **in, long len, const ASN1_ITEM *it, int tag, int aclass, char opt); -// ASN1_item_ex_i2d encodes |*pval| as a value of type |it| to |out| under the +// ASN1_item_ex_i2d encodes `*pval` as a value of type `it` to `out` under the // i2d output convention. It returns a non-zero length on success and -1 on -// error. If |tag| is -1. the tag and class come from |it|. Otherwise, the tag -// number is |tag| and the class is |aclass|. This is used for implicit tagging. +// error. If `tag` is -1. the tag and class come from `it`. Otherwise, the tag +// number is `tag` and the class is `aclass`. This is used for implicit tagging. // This function treats a missing value as an error, not an optional field. int ASN1_item_ex_i2d(ASN1_VALUE **pval, unsigned char **out, const ASN1_ITEM *it, int tag, int aclass); void ASN1_primitive_free(ASN1_VALUE **pval, const ASN1_ITEM *it); -// asn1_get_choice_selector returns the CHOICE selector value for |*pval|, which -// must of type |it|. +// asn1_get_choice_selector returns the CHOICE selector value for `*pval`, which +// must of type `it`. int asn1_get_choice_selector(ASN1_VALUE **pval, const ASN1_ITEM *it); int asn1_set_choice_selector(ASN1_VALUE **pval, int value, const ASN1_ITEM *it); -// asn1_get_field_ptr returns a pointer to the field in |*pval| corresponding to -// |tt|. +// asn1_get_field_ptr returns a pointer to the field in `*pval` corresponding to +// `tt`. ASN1_VALUE **asn1_get_field_ptr(ASN1_VALUE **pval, const ASN1_TEMPLATE *tt); -// asn1_do_adb returns the |ASN1_TEMPLATE| for the ANY DEFINED BY field |tt|, -// based on the selector INTEGER or OID in |*pval|. If |tt| is not an ADB field, -// it returns |tt|. If the selector does not match any value, it returns NULL. -// If |nullerr| is non-zero, it will additionally push an error to the error +// asn1_do_adb returns the `ASN1_TEMPLATE` for the ANY DEFINED BY field `tt`, +// based on the selector INTEGER or OID in `*pval`. If `tt` is not an ADB field, +// it returns `tt`. If the selector does not match any value, it returns NULL. +// If `nullerr` is non-zero, it will additionally push an error to the error // queue when there is no match. const ASN1_TEMPLATE *asn1_do_adb(ASN1_VALUE **pval, const ASN1_TEMPLATE *tt, int nullerr); @@ -253,19 +253,19 @@ void asn1_enc_init(ASN1_VALUE **pval, const ASN1_ITEM *it); void asn1_enc_free(ASN1_VALUE **pval, const ASN1_ITEM *it); -// asn1_enc_restore, if |*pval| has a saved encoding, writes it to |out| under -// the i2d output convention, sets |*len| to the length, and returns one. If it +// asn1_enc_restore, if `*pval` has a saved encoding, writes it to `out` under +// the i2d output convention, sets `*len` to the length, and returns one. If it // has no saved encoding, it returns zero. int asn1_enc_restore(int *len, unsigned char **out, ASN1_VALUE **pval, const ASN1_ITEM *it); -// asn1_enc_save saves |inlen| bytes from |in| as |*pval|'s saved encoding. It -// returns one on success and zero on error. If |buf| is non-NULL, |in| must -// point into |buf|. +// asn1_enc_save saves `inlen` bytes from `in` as `*pval`'s saved encoding. It +// returns one on success and zero on error. If `buf` is non-NULL, `in` must +// point into `buf`. int asn1_enc_save(ASN1_VALUE **pval, const uint8_t *in, size_t inlen, const ASN1_ITEM *it); -// asn1_encoding_clear clears the cached encoding in |enc|. +// asn1_encoding_clear clears the cached encoding in `enc`. void asn1_encoding_clear(ASN1_ENCODING *enc); typedef struct { @@ -276,8 +276,8 @@ unsigned long flags; } ASN1_STRING_TABLE; -// asn1_get_string_table_for_testing sets |*out_ptr| and |*out_len| to the table -// of built-in |ASN1_STRING_TABLE| values. It is exported for testing. +// asn1_get_string_table_for_testing sets `*out_ptr` and `*out_len` to the table +// of built-in `ASN1_STRING_TABLE` values. It is exported for testing. OPENSSL_EXPORT void asn1_get_string_table_for_testing( const ASN1_STRING_TABLE **out_ptr, size_t *out_len); @@ -287,14 +287,14 @@ long length); typedef int ASN1_i2d_func(ASN1_VALUE *a, unsigned char **in); -// An ASN1_ex_parse function should parse a value from |cbs| and set |*pval| to -// the result. It should return one on success and zero on failure. If |opt| is +// An ASN1_ex_parse function should parse a value from `cbs` and set `*pval` to +// the result. It should return one on success and zero on failure. If `opt` is // non-zero, the field may be optional. If an optional element is missing, the -// function should return one and consume zero bytes from |cbs|. +// function should return one and consume zero bytes from `cbs`. // -// If |opt| is non-zero, the function can assume that |*pval| is nullptr on -// entry. Otherwise, |*pval| may either be nullptr, or the result of -// |ASN1_ex_new_func|. The function may either write into the existing object, +// If `opt` is non-zero, the function can assume that `*pval` is nullptr on +// entry. Otherwise, `*pval` may either be nullptr, or the result of +// `ASN1_ex_new_func`. The function may either write into the existing object, // if any, or unconditionally make a new one. (The existing object comes from // tasn_new.cc recursively filling in objects before parsing into them.) typedef int ASN1_ex_parse(ASN1_VALUE **pval, CBS *cbs, const ASN1_ITEM *it, @@ -347,16 +347,16 @@ \ IMPLEMENT_EXTERN_ASN1(name, name##_extern_funcs) -// ASN1_TIME is an |ASN1_ITEM| whose ASN.1 type is X.509 Time (RFC 5280) and C -// type is |ASN1_TIME*|. +// ASN1_TIME is an `ASN1_ITEM` whose ASN.1 type is X.509 Time (RFC 5280) and C +// type is `ASN1_TIME*`. DECLARE_ASN1_ITEM(ASN1_TIME) -// DIRECTORYSTRING is an |ASN1_ITEM| whose ASN.1 type is X.509 DirectoryString -// (RFC 5280) and C type is |ASN1_STRING*|. +// DIRECTORYSTRING is an `ASN1_ITEM` whose ASN.1 type is X.509 DirectoryString +// (RFC 5280) and C type is `ASN1_STRING*`. DECLARE_ASN1_ITEM(DIRECTORYSTRING) -// DISPLAYTEXT is an |ASN1_ITEM| whose ASN.1 type is X.509 DisplayText (RFC -// 5280) and C type is |ASN1_STRING*|. +// DISPLAYTEXT is an `ASN1_ITEM` whose ASN.1 type is X.509 DisplayText (RFC +// 5280) and C type is `ASN1_STRING*`. DECLARE_ASN1_ITEM(DISPLAYTEXT) BSSL_NAMESPACE_END
diff --git a/crypto/bcm_support.h b/crypto/bcm_support.h index 7e39637..451e56a 100644 --- a/crypto/bcm_support.h +++ b/crypto/bcm_support.h
@@ -28,7 +28,7 @@ // from the operating system, if the operating system requires initialization. void CRYPTO_init_sysrand(); -// CRYPTO_sysrand fills |len| bytes at |buf| with entropy from the operating +// CRYPTO_sysrand fills `len` bytes at `buf` with entropy from the operating // system. void CRYPTO_sysrand(uint8_t *buf, size_t len); @@ -44,7 +44,7 @@ // the save fork generation. Note this logic transparently handles platforms // which always return zero. // -// This is not reliably supported on all platforms which implement |fork|, so it +// This is not reliably supported on all platforms which implement `fork`, so it // should only be used as a hardening measure. OPENSSL_EXPORT uint64_t CRYPTO_get_fork_generation();
diff --git a/crypto/bio/internal.h b/crypto/bio/internal.h index 77cd8a8..19b930c 100644 --- a/crypto/bio/internal.h +++ b/crypto/bio/internal.h
@@ -60,14 +60,14 @@ const BIO_METHOD *method; CRYPTO_EX_DATA ex_data; - // TODO(crbug.com/412269080): |init| and |shutdown| could be bitfields, or - // integrated into |flags|, to save memory. + // TODO(crbug.com/412269080): `init` and `shutdown` could be bitfields, or + // integrated into `flags`, to save memory. - // init is non-zero if this |BIO| has been initialised. + // init is non-zero if this `BIO` has been initialised. int init = 0; - // shutdown is often used by specific |BIO_METHOD|s to determine whether + // shutdown is often used by specific `BIO_METHOD`s to determine whether // they own some underlying resource. This flag can often be controlled by - // |BIO_set_close|. For example, whether an fd BIO closes the underlying fd + // `BIO_set_close`. For example, whether an fd BIO closes the underlying fd // when it, itself, is closed. int shutdown = 1; int flags = 0; @@ -76,8 +76,8 @@ // file descriptor. int num = 0; void *ptr = nullptr; - // next_bio points to the next |BIO| in a chain. This |BIO| owns a reference - // to |next_bio|. + // next_bio points to the next `BIO` in a chain. This `BIO` owns a reference + // to `next_bio`. Bio *next_bio = nullptr; // used by filter BIOs uint64_t num_read = 0, num_write = 0; @@ -88,16 +88,16 @@ #if !defined(OPENSSL_NO_SOCK) -// bio_ip_and_port_to_socket_and_addr creates a socket and fills in |*out_addr| -// and |*out_addr_length| with the correct values for connecting to |hostname| -// on |port_str|. It returns one on success or zero on error. +// bio_ip_and_port_to_socket_and_addr creates a socket and fills in `*out_addr` +// and `*out_addr_length` with the correct values for connecting to `hostname` +// on `port_str`. It returns one on success or zero on error. int bio_ip_and_port_to_socket_and_addr(int *out_sock, struct sockaddr_storage *out_addr, socklen_t *out_addr_length, const char *hostname, const char *port_str); -// bio_socket_nbio sets whether |sock| is non-blocking. It returns one on +// bio_socket_nbio sets whether `sock` is non-blocking. It returns one on // success and zero otherwise. int bio_socket_nbio(int sock, int on); @@ -106,17 +106,17 @@ // TODO(fork): remove all callers of this. void bio_clear_socket_error(); -// bio_sock_error returns the last socket error on |sock|. +// bio_sock_error returns the last socket error on `sock`. int bio_sock_error(int sock); -// bio_socket_should_retry returns non-zero if |return_value| indicates an error +// bio_socket_should_retry returns non-zero if `return_value` indicates an error // and the last socket error indicates that it's non-fatal. int bio_socket_should_retry(int return_value); #endif // !OPENSSL_NO_SOCK -// bio_errno_should_retry returns non-zero if |return_value| indicates an error -// and |errno| indicates that it's non-fatal. +// bio_errno_should_retry returns non-zero if `return_value` indicates an error +// and `errno` indicates that it's non-fatal. int bio_errno_should_retry(int return_value); BSSL_NAMESPACE_END
diff --git a/crypto/bytestring/internal.h b/crypto/bytestring/internal.h index 25a50f3..e1aa76f 100644 --- a/crypto/bytestring/internal.h +++ b/crypto/bytestring/internal.h
@@ -26,18 +26,18 @@ BSSL_NAMESPACE_BEGIN -// CBS_asn1_ber_to_der reads a BER element from |in|. If it finds +// CBS_asn1_ber_to_der reads a BER element from `in`. If it finds // indefinite-length elements or constructed strings then it converts the BER -// data to DER, sets |out| to the converted contents and |*out_storage| to a -// buffer which the caller must release with |OPENSSL_free|. Otherwise, it sets -// |out| to the original BER element in |in| and |*out_storage| to NULL. -// Additionally, |*in| will be advanced over the BER element. +// data to DER, sets `out` to the converted contents and `*out_storage` to a +// buffer which the caller must release with `OPENSSL_free`. Otherwise, it sets +// `out` to the original BER element in `in` and `*out_storage` to NULL. +// Additionally, `*in` will be advanced over the BER element. // // This function should successfully process any valid BER input, however it // will not convert all of BER's deviations from DER. BER is ambiguous between // implicitly-tagged SEQUENCEs of strings and implicitly-tagged constructed // strings. Implicitly-tagged strings must be parsed with -// |CBS_get_ber_implicitly_tagged_string| instead of |CBS_get_asn1|. The caller +// `CBS_get_ber_implicitly_tagged_string` instead of `CBS_get_asn1`. The caller // must also account for BER variations in the contents of a primitive. // // It returns one on success and zero otherwise. @@ -45,15 +45,15 @@ uint8_t **out_storage); // CBS_get_asn1_implicit_string parses a BER string of primitive type -// |inner_tag| implicitly-tagged with |outer_tag|. It sets |out| to the -// contents. If concatenation was needed, it sets |*out_storage| to a buffer -// which the caller must release with |OPENSSL_free|. Otherwise, it sets -// |*out_storage| to NULL. +// `inner_tag` implicitly-tagged with `outer_tag`. It sets `out` to the +// contents. If concatenation was needed, it sets `*out_storage` to a buffer +// which the caller must release with `OPENSSL_free`. Otherwise, it sets +// `*out_storage` to NULL. // // This function does not parse all of BER. It requires the string be // definite-length. Constructed strings are allowed, but all children of the // outermost element must be primitive. The caller should use -// |CBS_asn1_ber_to_der| before running this function. +// `CBS_asn1_ber_to_der` before running this function. // // It returns one on success and zero otherwise. OPENSSL_EXPORT int CBS_get_asn1_implicit_string(CBS *in, CBS *out, @@ -61,16 +61,16 @@ CBS_ASN1_TAG outer_tag, CBS_ASN1_TAG inner_tag); -// CBB_finish_i2d calls |CBB_finish| on |cbb| which must have been initialized -// with |CBB_init|. If |outp| is not NULL then the result is written to |*outp| -// and |*outp| is advanced just past the output. It returns the number of bytes +// CBB_finish_i2d calls `CBB_finish` on `cbb` which must have been initialized +// with `CBB_init`. If `outp` is not NULL then the result is written to `*outp` +// and `*outp` is advanced just past the output. It returns the number of bytes // in the result, whether written or not, or a negative value on error. // // This function may be used to help implement legacy i2d ASN.1 functions. OPENSSL_EXPORT int CBB_finish_i2d(CBB *cbb, uint8_t **outp); -// CBBAsSpan returns a span containing |cbb|'s contents. It does not flush -// |cbb|. The span is valid until the next operation to |cbb|. +// CBBAsSpan returns a span containing `cbb`'s contents. It does not flush +// `cbb`. The span is valid until the next operation to `cbb`. // // To avoid unfinalized length prefixes, it is a fatal error to call this on a // CBB with any active children. @@ -78,14 +78,14 @@ return Span(CBB_data(cbb), CBB_len(cbb)); } -// CBBFinishArray behaves like |CBB_finish| but stores the result in an Array. +// CBBFinishArray behaves like `CBB_finish` but stores the result in an Array. OPENSSL_EXPORT bool CBBFinishArray(CBB *cbb, Array<uint8_t> *out); -// D2IFromCBS takes a functor of type |Unique<T>(CBS*)| and implements the d2i +// D2IFromCBS takes a functor of type `Unique<T>(CBS*)` and implements the d2i // calling convention. For compatibility with functions that don't tag their -// return value (e.g. public APIs), |T*(CBS)| is also accepted. The callback can -// assume that the |CBS|'s length fits in |long|. The callback should not access -// |out|, |inp|, or |len| directly. +// return value (e.g. public APIs), `T*(CBS)` is also accepted. The callback can +// assume that the `CBS`'s length fits in `long`. The callback should not access +// `out`, `inp`, or `len` directly. template <typename T, typename CBSFunc> inline T *D2IFromCBS(T **out, const uint8_t **inp, long len, CBSFunc func) { static_assert(std::is_invocable_v<CBSFunc, CBS *>); @@ -110,9 +110,9 @@ return ret.release(); } -// I2DFromCBB takes a functor of type |bool(CBB*)| and implements the i2d -// calling convention. It internally makes a |CBB| with the specified initial -// capacity. The callback should not access |outp| directly. +// I2DFromCBB takes a functor of type `bool(CBB*)` and implements the i2d +// calling convention. It internally makes a `CBB` with the specified initial +// capacity. The callback should not access `outp` directly. template <typename CBBFunc> inline int I2DFromCBB(size_t initial_capacity, uint8_t **outp, CBBFunc func) { static_assert(std::is_invocable_v<CBBFunc, CBB *>);
diff --git a/crypto/chacha/internal.h b/crypto/chacha/internal.h index a758055..04c20a4 100644 --- a/crypto/chacha/internal.h +++ b/crypto/chacha/internal.h
@@ -84,11 +84,11 @@ #endif #if defined(CHACHA20_ASM_NOHW) -// ChaCha20_ctr32_nohw encrypts |in_len| bytes from |in| and writes the result -// to |out|. If |in| and |out| alias, they must be equal. |in_len| may not be +// ChaCha20_ctr32_nohw encrypts `in_len` bytes from `in` and writes the result +// to `out`. If `in` and `out` alias, they must be equal. `in_len` may not be // zero. // -// |counter[0]| is the initial 32-bit block counter, and the remainder is the +// `counter[0]` is the initial 32-bit block counter, and the remainder is the // 96-bit nonce. If the counter overflows, the output is undefined. The function // will produce output, but the output may vary by machine and may not be // self-consistent. (On some architectures, the assembly implements a mix of
diff --git a/crypto/cipher/internal.h b/crypto/cipher/internal.h index e6ce207..0293e34 100644 --- a/crypto/cipher/internal.h +++ b/crypto/cipher/internal.h
@@ -28,23 +28,23 @@ BSSL_NAMESPACE_BEGIN // EVP_tls_cbc_get_padding determines the padding from the decrypted, TLS, CBC -// record in |in|. This decrypted record should not include any "decrypted" +// record in `in`. This decrypted record should not include any "decrypted" // explicit IV. If the record is publicly invalid, it returns zero. Otherwise, -// it returns one and sets |*out_padding_ok| to all ones (0xfff..f) if the -// padding is valid and zero otherwise. It then sets |*out_len| to the length -// with the padding removed or |in_len| if invalid. +// it returns one and sets `*out_padding_ok` to all ones (0xfff..f) if the +// padding is valid and zero otherwise. It then sets `*out_len` to the length +// with the padding removed or `in_len` if invalid. // // If the function returns one, it runs in time independent of the contents of -// |in|. It is also guaranteed that, independent of |*out_padding_ok|, |mac_len| -// <= |*out_len| <= |in_len|, satisfying |EVP_tls_cbc_copy_mac|'s precondition. +// `in`. It is also guaranteed that, independent of `*out_padding_ok`, `mac_len` +// <= `*out_len` <= `in_len`, satisfying `EVP_tls_cbc_copy_mac`'s precondition. int EVP_tls_cbc_remove_padding(crypto_word_t *out_padding_ok, size_t *out_len, const uint8_t *in, size_t in_len, size_t block_size, size_t mac_size); -// EVP_tls_cbc_copy_mac copies |md_size| bytes from the end of the first -// |in_len| bytes of |in| to |out| in constant time (independent of the concrete -// value of |in_len|, which may vary within a 256-byte window). |in| must point -// to a buffer of |orig_len| bytes. +// EVP_tls_cbc_copy_mac copies `md_size` bytes from the end of the first +// `in_len` bytes of `in` to `out` in constant time (independent of the concrete +// value of `in_len`, which may vary within a 256-byte window). `in` must point +// to a buffer of `orig_len` bytes. // // On entry: // orig_len >= in_len >= md_size @@ -52,14 +52,14 @@ void EVP_tls_cbc_copy_mac(uint8_t *out, size_t md_size, const uint8_t *in, size_t in_len, size_t orig_len); -// EVP_tls_cbc_record_digest_supported returns 1 iff |md| is a hash function +// EVP_tls_cbc_record_digest_supported returns 1 iff `md` is a hash function // which EVP_tls_cbc_digest_record supports. int EVP_tls_cbc_record_digest_supported(const EVP_MD *md); -// EVP_sha1_final_with_secret_suffix computes the result of hashing |len| bytes -// from |in| to |ctx| and writes the resulting hash to |out|. |len| is treated -// as secret and must be at most |max_len|, which is treated as public. |in| -// must point to a buffer of at least |max_len| bytes. It returns one on success +// EVP_sha1_final_with_secret_suffix computes the result of hashing `len` bytes +// from `in` to `ctx` and writes the resulting hash to `out`. `len` is treated +// as secret and must be at most `max_len`, which is treated as public. `in` +// must point to a buffer of at least `max_len` bytes. It returns one on success // and zero if inputs are too long. // // This function is exported for unit tests. @@ -68,7 +68,7 @@ size_t max_len); // EVP_sha256_final_with_secret_suffix acts like -// |EVP_sha1_final_with_secret_suffix|, but for SHA-256. +// `EVP_sha1_final_with_secret_suffix`, but for SHA-256. // // This function is exported for unit tests. OPENSSL_EXPORT int EVP_sha256_final_with_secret_suffix( @@ -90,7 +90,7 @@ // trailer: a buffer, of public length, containing the remainder of the // plaintext as a prefix. // data_in_trailer_size: the secret, reported length of the data portion in -// |trailer| once the padding and MAC have been removed. +// `trailer` once the padding and MAC have been removed. // // On entry: by virtue of having been through one of the remove_padding // functions, above, we know that data_plus_mac_size is large enough to contain @@ -149,9 +149,9 @@ } // chacha20_poly1305_open is defined in chacha20_poly1305_*.pl. It decrypts -// |plaintext_len| bytes from |ciphertext| and writes them to |out_plaintext|. -// Additional input parameters are passed in |aead_data->in|. On exit, it will -// write calculated tag value to |aead_data->out.tag|, which the caller must +// `plaintext_len` bytes from `ciphertext` and writes them to `out_plaintext`. +// Additional input parameters are passed in `aead_data->in`. On exit, it will +// write calculated tag value to `aead_data->out.tag`, which the caller must // check. #if defined(OPENSSL_X86_64) extern "C" void chacha20_poly1305_open_sse41( @@ -182,10 +182,10 @@ #endif // chacha20_poly1305_open is defined in chacha20_poly1305_*.pl. It encrypts -// |plaintext_len| bytes from |plaintext| and writes them to |out_ciphertext|. -// Additional input parameters are passed in |aead_data->in|. The calculated tag -// value is over the computed ciphertext concatenated with |extra_ciphertext| -// and written to |aead_data->out.tag|. +// `plaintext_len` bytes from `plaintext` and writes them to `out_ciphertext`. +// Additional input parameters are passed in `aead_data->in`. The calculated tag +// value is over the computed ciphertext concatenated with `extra_ciphertext` +// and written to `aead_data->out.tag`. #if defined(OPENSSL_X86_64) extern "C" void chacha20_poly1305_seal_sse41( uint8_t *out_ciphertext, const uint8_t *plaintext, size_t plaintext_len,
diff --git a/crypto/conf/internal.h b/crypto/conf/internal.h index 7fe35aa..f924390 100644 --- a/crypto/conf/internal.h +++ b/crypto/conf/internal.h
@@ -36,14 +36,14 @@ BSSL_NAMESPACE_BEGIN -// CONF_VALUE_new returns a freshly allocated and zeroed |CONF_VALUE|. +// CONF_VALUE_new returns a freshly allocated and zeroed `CONF_VALUE`. CONF_VALUE *CONF_VALUE_new(); -// CONF_parse_list takes a list separated by 'sep' and calls |list_cb| giving +// CONF_parse_list takes a list separated by 'sep' and calls `list_cb` giving // the start and length of each member, optionally stripping leading and // trailing whitespace. This can be used to parse comma separated lists for -// example. If |list_cb| returns <= 0, then the iteration is halted and that -// value is returned immediately. Otherwise it returns one. Note that |list_cb| +// example. If `list_cb` returns <= 0, then the iteration is halted and that +// value is returned immediately. Otherwise it returns one. Note that `list_cb` // may be called on an empty member. OPENSSL_EXPORT int CONF_parse_list( const char *list, char sep, int remove_whitespace,
diff --git a/crypto/cpu_arm_linux.h b/crypto/cpu_arm_linux.h index b01ee54..bea577a 100644 --- a/crypto/cpu_arm_linux.h +++ b/crypto/cpu_arm_linux.h
@@ -41,8 +41,8 @@ #define CRYPTO_HWCAP2_SHA1 (1 << 2) #define CRYPTO_HWCAP2_SHA2 (1 << 3) -// SplitStringView finds the first occurrence of |sep| in |in| and, if found, -// sets |*out_left| and |*out_right| to |in| split before and after |sep|, and +// SplitStringView finds the first occurrence of `sep` in `in` and, if found, +// sets `*out_left` and `*out_right` to `in` split before and after `sep`, and // returns true. If not found, it returns false. inline bool SplitStringView(std::string_view *out_left, std::string_view *out_right, std::string_view in, @@ -56,23 +56,23 @@ return true; } -// GetDelimited reads a |sep|-delimited entry from |s|, writing it to |out| and -// updating |s| to point beyond it. It returns true on success and false if |s| -// is empty. If |s| has no copies of |sep| and is non-empty, it reads the entire -// string to |out|. +// GetDelimited reads a `sep`-delimited entry from `s`, writing it to `out` and +// updating `s` to point beyond it. It returns true on success and false if `s` +// is empty. If `s` has no copies of `sep` and is non-empty, it reads the entire +// string to `out`. inline bool GetDelimited(std::string_view *s, std::string_view *out, char sep) { if (s->empty()) { return false; } if (!SplitStringView(out, s, *s, sep)) { - // |s| had no instances of |sep|. Return the entire string. + // `s` had no instances of `sep`. Return the entire string. *out = *s; *s = std::string_view(); } return true; } -// TrimStringView removes leading and trailing whitespace from |s|. +// TrimStringView removes leading and trailing whitespace from `s`. inline std::string_view TrimStringView(std::string_view s) { size_t pos = s.find_first_not_of(" \t"); if (pos == std::string_view::npos) { @@ -84,11 +84,11 @@ return s.substr(0, pos + 1); } -// ExtractCpuinfoField extracts a /proc/cpuinfo field named |field| from |in|. +// ExtractCpuinfoField extracts a /proc/cpuinfo field named `field` from `in`. // If found, it returns the value. Otherwise, it returns the empty string. inline std::string_view ExtractCpuinfoField(std::string_view in, std::string_view field) { - // Process |in| one line at a time. + // Process `in` one line at a time. std::string_view line; while (GetDelimited(&in, &line, '\n')) { std::string_view key, value; @@ -103,8 +103,8 @@ return {}; } -// HasListItem treats |list| as a space-separated list of items and returns -// whether |item| is contained in |list|. +// HasListItem treats `list` as a space-separated list of items and returns +// whether `item` is contained in `list`. inline bool HasListItem(std::string_view list, std::string_view item) { std::string_view feature; while (GetDelimited(&list, &feature, ' ')) { @@ -115,8 +115,8 @@ return false; } -// GetHWCAP2FromCpuinfo returns an equivalent ARM |AT_HWCAP2| value from -// |cpuinfo|. +// GetHWCAP2FromCpuinfo returns an equivalent ARM `AT_HWCAP2` value from +// `cpuinfo`. inline unsigned long GetHWCAP2FromCpuinfo(std::string_view cpuinfo) { std::string_view features = ExtractCpuinfoField(cpuinfo, "Features"); unsigned long ret = 0;
diff --git a/crypto/curve25519/curve25519_tables.h b/crypto/curve25519/curve25519_tables.h index 942336d..0869238 100644 --- a/crypto/curve25519/curve25519_tables.h +++ b/crypto/curve25519/curve25519_tables.h
@@ -52,7 +52,7 @@ // one. The standard table is 30,720 bytes while this one is just 960. // // This table contains 15 pairs of group elements, (x, y), where each field -// element is serialised with |fe_tobytes|. If |i| is the index of the group +// element is serialised with `fe_tobytes`. If `i` is the index of the group // element then consider i+1 as a four-bit number: (i₀, i₁, i₂, i₃) (where i₀ // is the most significant bit). The value of the group element is then: // (i₀×2^192 + i₁×2^128 + i₂×2^64 + i₃)G, where G is the generator.
diff --git a/crypto/des/internal.h b/crypto/des/internal.h index 6bb46ff..221f309 100644 --- a/crypto/des/internal.h +++ b/crypto/des/internal.h
@@ -24,7 +24,7 @@ BSSL_NAMESPACE_BEGIN // TODO(davidben): Ideally these macros would be replaced with -// |CRYPTO_load_u32_le| and |CRYPTO_store_u32_le|. +// `CRYPTO_load_u32_le` and `CRYPTO_store_u32_le`. #define c2l(c, l) \ do { \ @@ -129,7 +129,7 @@ // Private functions. // -// These functions are only exported for use in |decrepit|. +// These functions are only exported for use in `decrepit`. OPENSSL_EXPORT void DES_decrypt3(uint32_t data[2], const DES_key_schedule *ks1, const DES_key_schedule *ks2,
diff --git a/crypto/dsa/internal.h b/crypto/dsa/internal.h index 70f77e7..9938732 100644 --- a/crypto/dsa/internal.h +++ b/crypto/dsa/internal.h
@@ -47,7 +47,7 @@ ~DSAImpl(); }; -// dsa_check_key performs cheap self-checks on |dsa|, and ensures it is within +// dsa_check_key performs cheap self-checks on `dsa`, and ensures it is within // DoS bounds. It returns one on success and zero on error. int dsa_check_key(const DSAImpl *dsa);
diff --git a/crypto/ec/internal.h b/crypto/ec/internal.h index 6e46485..902eb81 100644 --- a/crypto/ec/internal.h +++ b/crypto/ec/internal.h
@@ -26,21 +26,21 @@ // Parsing functions. -// ec_key_parse_curve_name behaves like |EC_KEY_parse_curve_name| but only -// supports the groups in |allowed_groups|. If no syntax errors were found but -// the group is unknown, it will fail with an error of |EC_R_UNKNOWN_GROUP|. +// ec_key_parse_curve_name behaves like `EC_KEY_parse_curve_name` but only +// supports the groups in `allowed_groups`. If no syntax errors were found but +// the group is unknown, it will fail with an error of `EC_R_UNKNOWN_GROUP`. const EC_GROUP *ec_key_parse_curve_name( CBS *cbs, bssl::Span<const EC_GROUP *const> allowed_groups); -// ec_key_parse_parameters behaves like |EC_KEY_parse_parameters| but only -// supports the groups in |allowed_groups|. If no syntax errors were found but -// the group is unknown, it will fail with an error of |EC_R_UNKNOWN_GROUP|. +// ec_key_parse_parameters behaves like `EC_KEY_parse_parameters` but only +// supports the groups in `allowed_groups`. If no syntax errors were found but +// the group is unknown, it will fail with an error of `EC_R_UNKNOWN_GROUP`. const EC_GROUP *ec_key_parse_parameters( CBS *cbs, bssl::Span<const EC_GROUP *const> allowed_groups); -// ec_key_parse_private_key behaves like |EC_KEY_parse_private_key| but only -// supports the groups in |allowed_groups|. If |group| is non-NULL, -// |allowed_groups| is ignored and instead only |group| is supported. +// ec_key_parse_private_key behaves like `EC_KEY_parse_private_key` but only +// supports the groups in `allowed_groups`. If `group` is non-NULL, +// `allowed_groups` is ignored and instead only `group` is supported. // // TODO(crbug.com/boringssl/414361735): This should return a bssl::UniquePtr, // but cannot until it is made C++ linkage. @@ -51,46 +51,46 @@ // Hash-to-curve. // -// Internal |EC_JACOBIAN| versions of the corresponding public APIs. +// Internal `EC_JACOBIAN` versions of the corresponding public APIs. -// ec_hash_to_curve_p256_xmd_sha256_sswu hashes |msg| to a point on |group| and -// writes the result to |out|, implementing the P256_XMD:SHA-256_SSWU_RO_ suite +// ec_hash_to_curve_p256_xmd_sha256_sswu hashes `msg` to a point on `group` and +// writes the result to `out`, implementing the P256_XMD:SHA-256_SSWU_RO_ suite // from RFC 9380. It returns one on success and zero on error. OPENSSL_EXPORT int ec_hash_to_curve_p256_xmd_sha256_sswu( const EC_GROUP *group, EC_JACOBIAN *out, const uint8_t *dst, size_t dst_len, const uint8_t *msg, size_t msg_len); -// ec_hash_to_curve_p384_xmd_sha384_sswu hashes |msg| to a point on |group| and -// writes the result to |out|, implementing the P384_XMD:SHA-384_SSWU_RO_ suite +// ec_hash_to_curve_p384_xmd_sha384_sswu hashes `msg` to a point on `group` and +// writes the result to `out`, implementing the P384_XMD:SHA-384_SSWU_RO_ suite // from RFC 9380. It returns one on success and zero on error. OPENSSL_EXPORT int ec_hash_to_curve_p384_xmd_sha384_sswu( const EC_GROUP *group, EC_JACOBIAN *out, const uint8_t *dst, size_t dst_len, const uint8_t *msg, size_t msg_len); -// ec_encode_to_curve_p256_xmd_sha256_sswu hashes |msg| to a point on |group| -// and writes the result to |out|, implementing the P256_XMD:SHA-256_SSWU_NU_ +// ec_encode_to_curve_p256_xmd_sha256_sswu hashes `msg` to a point on `group` +// and writes the result to `out`, implementing the P256_XMD:SHA-256_SSWU_NU_ // suite from RFC 9380. It returns one on success and zero on error. OPENSSL_EXPORT int ec_encode_to_curve_p256_xmd_sha256_sswu( const EC_GROUP *group, EC_JACOBIAN *out, const uint8_t *dst, size_t dst_len, const uint8_t *msg, size_t msg_len); -// ec_encode_to_curve_p384_xmd_sha384_sswu hashes |msg| to a point on |group| -// and writes the result to |out|, implementing the P384_XMD:SHA-384_SSWU_NU_ +// ec_encode_to_curve_p384_xmd_sha384_sswu hashes `msg` to a point on `group` +// and writes the result to `out`, implementing the P384_XMD:SHA-384_SSWU_NU_ // suite from RFC 9380. It returns one on success and zero on error. OPENSSL_EXPORT int ec_encode_to_curve_p384_xmd_sha384_sswu( const EC_GROUP *group, EC_JACOBIAN *out, const uint8_t *dst, size_t dst_len, const uint8_t *msg, size_t msg_len); -// ec_hash_to_scalar_p384_xmd_sha384 hashes |msg| to a scalar on |group| -// and writes the result to |out|, using the hash_to_field operation from the +// ec_hash_to_scalar_p384_xmd_sha384 hashes `msg` to a scalar on `group` +// and writes the result to `out`, using the hash_to_field operation from the // P384_XMD:SHA-384_SSWU_RO_ suite from RFC 9380, but generating a value modulo // the group order rather than a field element. OPENSSL_EXPORT int ec_hash_to_scalar_p384_xmd_sha384( const EC_GROUP *group, EC_SCALAR *out, const uint8_t *dst, size_t dst_len, const uint8_t *msg, size_t msg_len); -// ec_hash_to_curve_p384_xmd_sha512_sswu_draft07 hashes |msg| to a point on -// |group| and writes the result to |out|, implementing the +// ec_hash_to_curve_p384_xmd_sha512_sswu_draft07 hashes `msg` to a point on +// `group` and writes the result to `out`, implementing the // P384_XMD:SHA-512_SSWU_RO_ suite from draft-irtf-cfrg-hash-to-curve-07. It // returns one on success and zero on error. // @@ -99,8 +99,8 @@ const EC_GROUP *group, EC_JACOBIAN *out, const uint8_t *dst, size_t dst_len, const uint8_t *msg, size_t msg_len); -// ec_hash_to_scalar_p384_xmd_sha512_draft07 hashes |msg| to a scalar on |group| -// and writes the result to |out|, using the hash_to_field operation from the +// ec_hash_to_scalar_p384_xmd_sha512_draft07 hashes `msg` to a scalar on `group` +// and writes the result to `out`, using the hash_to_field operation from the // P384_XMD:SHA-512_SSWU_RO_ suite from draft-irtf-cfrg-hash-to-curve-07, but // generating a value modulo the group order rather than a field element. //
diff --git a/crypto/err/internal.h b/crypto/err/internal.h index e81768c..d0f722d 100644 --- a/crypto/err/internal.h +++ b/crypto/err/internal.h
@@ -23,19 +23,19 @@ // Private error queue functions. // ERR_SAVE_STATE contains a saved representation of the error queue. It is -// slightly more compact than |ERR_STATE| as the error queue will typically not -// contain |ERR_NUM_ERRORS| entries. +// slightly more compact than `ERR_STATE` as the error queue will typically not +// contain `ERR_NUM_ERRORS` entries. typedef struct err_save_state_st ERR_SAVE_STATE; -// ERR_SAVE_STATE_free releases all memory associated with |state|. +// ERR_SAVE_STATE_free releases all memory associated with `state`. OPENSSL_EXPORT void ERR_SAVE_STATE_free(ERR_SAVE_STATE *state); -// ERR_save_state returns a newly-allocated |ERR_SAVE_STATE| structure +// ERR_save_state returns a newly-allocated `ERR_SAVE_STATE` structure // containing the current state of the error queue or NULL on allocation -// error. It should be released with |ERR_SAVE_STATE_free|. +// error. It should be released with `ERR_SAVE_STATE_free`. OPENSSL_EXPORT ERR_SAVE_STATE *ERR_save_state(); -// ERR_restore_state clears the error queue and replaces it with |state|. +// ERR_restore_state clears the error queue and replaces it with `state`. OPENSSL_EXPORT void ERR_restore_state(const ERR_SAVE_STATE *state); BORINGSSL_MAKE_DELETER(ERR_SAVE_STATE, ERR_SAVE_STATE_free)
diff --git a/crypto/evp/internal.h b/crypto/evp/internal.h index 10485b6..d843933 100644 --- a/crypto/evp/internal.h +++ b/crypto/evp/internal.h
@@ -36,7 +36,7 @@ BSSL_NAMESPACE_END struct evp_pkey_alg_st { - // method and pkey_method implement operations for this |EVP_PKEY_ALG|. + // method and pkey_method implement operations for this `EVP_PKEY_ALG`. const bssl::EVP_PKEY_ASN1_METHOD *method; const bssl::EVP_PKEY_CTX_METHOD *pkey_method; }; @@ -50,7 +50,7 @@ }; struct evp_pkey_asn1_method_st { - // pkey_id contains one of the |EVP_PKEY_*| values and corresponds to the OID + // pkey_id contains one of the `EVP_PKEY_*` values and corresponds to the OID // in the key type's AlgorithmIdentifier. int pkey_id; uint8_t oid[9]; @@ -58,53 +58,53 @@ const EVP_PKEY_CTX_METHOD *pkey_method; - // pub_decode decodes |params| and |key| as a SubjectPublicKeyInfo - // and writes the result into |out|. It returns |evp_decode_ok| on success, - // and |evp_decode_error| on error, and |evp_decode_unsupported| if the input - // was not supported by this |EVP_PKEY_ALG|. In case of - // |evp_decode_unsupported|, it does not add an error to the error queue. May - // modify |params| and |key|. Callers must make a copy if calling in a loop. + // pub_decode decodes `params` and `key` as a SubjectPublicKeyInfo + // and writes the result into `out`. It returns `evp_decode_ok` on success, + // and `evp_decode_error` on error, and `evp_decode_unsupported` if the input + // was not supported by this `EVP_PKEY_ALG`. In case of + // `evp_decode_unsupported`, it does not add an error to the error queue. May + // modify `params` and `key`. Callers must make a copy if calling in a loop. // - // |params| is the AlgorithmIdentifier after the OBJECT IDENTIFIER type field, - // and |key| is the contents of the subjectPublicKey with the leading padding + // `params` is the AlgorithmIdentifier after the OBJECT IDENTIFIER type field, + // and `key` is the contents of the subjectPublicKey with the leading padding // byte checked and removed. Although X.509 uses BIT STRINGs to represent // SubjectPublicKeyInfo, every key type defined encodes the key as a byte // string with the same conversion to BIT STRING. evp_decode_result_t (*pub_decode)(const EVP_PKEY_ALG *alg, EvpPkey *out, CBS *params, CBS *key); - // pub_encode encodes |key| as a SubjectPublicKeyInfo and appends the result - // to |out|. It returns one on success and zero on error. + // pub_encode encodes `key` as a SubjectPublicKeyInfo and appends the result + // to `out`. It returns one on success and zero on error. int (*pub_encode)(CBB *out, const EvpPkey *key); bool (*pub_equal)(const EvpPkey *a, const EvpPkey *b); - // pub_present returns true iff the |pk| has a public key. (If so, validity + // pub_present returns true iff the `pk` has a public key. (If so, validity // is not guaranteed and should be checked separately.) bool (*pub_present)(const EvpPkey *pk); - // pub_copy sets the key data of |out| to a newly allocated key data structure - // which contains a copy of only the public key of |pk|, freeing any key - // previously in |out|. Returns true on success or false on failure. + // pub_copy sets the key data of `out` to a newly allocated key data structure + // which contains a copy of only the public key of `pk`, freeing any key + // previously in `out`. Returns true on success or false on failure. bool (*pub_copy)(EvpPkey *out, const EvpPkey *pk); - // priv_decode decodes |params| and |key| as a PrivateKeyInfo and writes the - // result into |out|. It returns |evp_decode_ok| on success, and - // |evp_decode_error| on error, and |evp_decode_unsupported| if the key type - // was not supported by this |EVP_PKEY_ALG|. In case of - // |evp_decode_unsupported|, it does not add an error to the error queue. May - // modify |params| and |key|. Callers must make a copy if calling in a loop. + // priv_decode decodes `params` and `key` as a PrivateKeyInfo and writes the + // result into `out`. It returns `evp_decode_ok` on success, and + // `evp_decode_error` on error, and `evp_decode_unsupported` if the key type + // was not supported by this `EVP_PKEY_ALG`. In case of + // `evp_decode_unsupported`, it does not add an error to the error queue. May + // modify `params` and `key`. Callers must make a copy if calling in a loop. // - // |params| is the AlgorithmIdentifier after the OBJECT IDENTIFIER type field, - // and |key| is the contents of the OCTET STRING privateKey field. + // `params` is the AlgorithmIdentifier after the OBJECT IDENTIFIER type field, + // and `key` is the contents of the OCTET STRING privateKey field. evp_decode_result_t (*priv_decode)(const EVP_PKEY_ALG *alg, EvpPkey *out, CBS *params, CBS *key); - // priv_encode encodes |key| as a PrivateKeyInfo and appends the result to - // |out|. It returns one on success and zero on error. + // priv_encode encodes `key` as a PrivateKeyInfo and appends the result to + // `out`. It returns one on success and zero on error. int (*priv_encode)(CBB *out, const EvpPkey *key); - // priv_present returns true iff the |pk| has a private key. (If so, validity + // priv_present returns true iff the `pk` has a private key. (If so, validity // is not guaranteed and should be checked separately.) bool (*priv_present)(const EvpPkey *pk); @@ -116,9 +116,9 @@ int (*get_pub_raw)(const EvpPkey *pkey, uint8_t *out, size_t *out_len); // TODO(davidben): Can these be merged with the functions above? OpenSSL does - // not implement |EVP_PKEY_get_raw_public_key|, etc., for |EVP_PKEY_EC|, but + // not implement `EVP_PKEY_get_raw_public_key`, etc., for `EVP_PKEY_EC`, but // the distinction seems unimportant. OpenSSL 3.0 has since renamed - // |EVP_PKEY_get1_tls_encodedpoint| to |EVP_PKEY_get1_encoded_public_key|, and + // `EVP_PKEY_get1_tls_encodedpoint` to `EVP_PKEY_get1_encoded_public_key`, and // what is the difference between "raw" and an "encoded" public key. // // One nuisance is the notion of "raw" is slightly ambiguous for EC keys. Is @@ -126,7 +126,7 @@ int (*set1_tls_encodedpoint)(EvpPkey *pkey, const uint8_t *in, size_t len); size_t (*get1_tls_encodedpoint)(const EvpPkey *pkey, uint8_t **out_ptr); - // pkey_opaque returns 1 if the |pk| is opaque. Opaque keys are backed by + // pkey_opaque returns 1 if the `pk` is opaque. Opaque keys are backed by // custom implementations which do not expose key material and parameters. int (*pkey_opaque)(const EvpPkey *pk); @@ -144,7 +144,7 @@ public: EvpPkey(); - // pkey contains a pointer to a structure dependent on |ameth|. + // pkey contains a pointer to a structure dependent on `ameth`. void *pkey = nullptr; // ameth contains a pointer to a method table that determines the key type, or @@ -175,12 +175,12 @@ #define EVP_PKEY_OP_TYPE_GEN (EVP_PKEY_OP_KEYGEN | EVP_PKEY_OP_PARAMGEN) -// EVP_PKEY_CTX_ctrl performs |cmd| on |ctx|. The |keytype| and |optype| +// EVP_PKEY_CTX_ctrl performs `cmd` on `ctx`. The `keytype` and `optype` // arguments can be -1 to specify that any type and operation are acceptable, -// otherwise |keytype| must match the type of |ctx| and the bits of |optype| -// must intersect the operation flags set on |ctx|. +// otherwise `keytype` must match the type of `ctx` and the bits of `optype` +// must intersect the operation flags set on `ctx`. // -// The |p1| and |p2| arguments depend on the value of |cmd|. +// The `p1` and `p2` arguments depend on the value of `cmd`. // // It returns one on success and zero on error. OPENSSL_EXPORT int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, @@ -189,14 +189,14 @@ #define EVP_PKEY_CTRL_MD 1 #define EVP_PKEY_CTRL_GET_MD 2 -// EVP_PKEY_CTRL_PEER_KEY is called with different values of |p1|: -// 0: Is called from |EVP_PKEY_derive_set_peer| and |p2| contains a peer key. +// EVP_PKEY_CTRL_PEER_KEY is called with different values of `p1`: +// 0: Is called from `EVP_PKEY_derive_set_peer` and `p2` contains a peer key. // If the return value is <= 0, the key is rejected. -// 1: Is called at the end of |EVP_PKEY_derive_set_peer| and |p2| contains a +// 1: Is called at the end of `EVP_PKEY_derive_set_peer` and `p2` contains a // peer key. If the return value is <= 0, the key is rejected. -// 2: Is called with |p2| == NULL to test whether the peer's key was used. +// 2: Is called with `p2` == NULL to test whether the peer's key was used. // (EC)DH always return one in this case. -// 3: Is called with |p2| == NULL to set whether the peer's key was used. +// 3: Is called with `p2` == NULL to set whether the peer's key was used. // (EC)DH always return one in this case. This was only used for GOST. #define EVP_PKEY_CTRL_PEER_KEY 3 @@ -231,7 +231,7 @@ // TODO(crbug.com/487376811): Ideally this destructor should be virtual so // that we can emit vtables in libcrypto. In that case we would be able to - // replace |pmeth| with virtual methods and subclassing. + // replace `pmeth` with virtual methods and subclassing. ~EvpPkeyCtx(); // Method associated with this operation @@ -240,10 +240,10 @@ bssl::UniquePtr<EvpPkey> pkey; // Peer key for key agreement, may be nullptr bssl::UniquePtr<EvpPkey> peerkey; - // operation contains one of the |EVP_PKEY_OP_*| values. + // operation contains one of the `EVP_PKEY_OP_*` values. int operation = EVP_PKEY_OP_UNDEFINED; // Algorithm specific data. - // TODO(crbug.com/487376811): Since a |EVP_PKEY_CTX| never has its type change + // TODO(crbug.com/487376811): Since a `EVP_PKEY_CTX` never has its type change // after creation, this should instead be a base class, with the // algorithm-specific data on the subclass, coming from the same allocation. void *data = nullptr; @@ -252,7 +252,7 @@ struct evp_pkey_ctx_method_st { int pkey_id; - // |alg| may be nullptr. If non-null, |ctx| will have a key set. + // `alg` may be nullptr. If non-null, `ctx` will have a key set. int (*init)(EvpPkeyCtx *ctx, const EVP_PKEY_ALG *alg); int (*copy)(EvpPkeyCtx *dst, EvpPkeyCtx *src); void (*cleanup)(EvpPkeyCtx *ctx); @@ -368,27 +368,27 @@ } }; -// evp_pkey_ec_no_curve returns an internal curveless EC |EVP_PKEY_ALG|. This +// evp_pkey_ec_no_curve returns an internal curveless EC `EVP_PKEY_ALG`. This // cannot be used to parse anything and is only useful for key generation. const EVP_PKEY_ALG *evp_pkey_ec_no_curve(); -// evp_pkey_hkdf returns an internal |EVP_PKEY_ALG| used to implement -// |EVP_PKEY_HKDF|. It has no associated key type. +// evp_pkey_hkdf returns an internal `EVP_PKEY_ALG` used to implement +// `EVP_PKEY_HKDF`. It has no associated key type. const EVP_PKEY_ALG *evp_pkey_hkdf(); -// evp_pkey_ctx_new_alg behaves like |EVP_PKEY_CTX_new_id| but takes an -// |EVP_PKEY_ALG|. +// evp_pkey_ctx_new_alg behaves like `EVP_PKEY_CTX_new_id` but takes an +// `EVP_PKEY_ALG`. UniquePtr<EvpPkeyCtx> evp_pkey_ctx_new_alg(const EVP_PKEY_ALG *alg); -// evp_pkey_set0 sets |pkey|'s method to |method| and data to |pkey_data|, +// evp_pkey_set0 sets `pkey`'s method to `method` and data to `pkey_data`, // freeing any key that may previously have been configured. This function takes -// ownership of |pkey_data|, which must be of the type expected by |method|. +// ownership of `pkey_data`, which must be of the type expected by `method`. void evp_pkey_set0(EvpPkey *pkey, const EVP_PKEY_ASN1_METHOD *method, void *pkey_data); inline auto GetDefaultEVPAlgorithms() { - // A set of algorithms to use by default in |EVP_parse_public_key| and - // |EVP_parse_private_key|. + // A set of algorithms to use by default in `EVP_parse_public_key` and + // `EVP_parse_private_key`. return std::array{ EVP_pkey_ec_p224(), EVP_pkey_ec_p256(), @@ -403,7 +403,7 @@ EVP_pkey_ml_kem_768(), EVP_pkey_ml_kem_1024(), // TODO(crbug.com/438761503): Remove DSA from this set, after callers that - // need DSA pass in |EVP_pkey_dsa| explicitly. + // need DSA pass in `EVP_pkey_dsa` explicitly. EVP_pkey_dsa(), }; }
diff --git a/crypto/fipsmodule/aes/internal.h b/crypto/fipsmodule/aes/internal.h index db62703..3ee356c 100644 --- a/crypto/fipsmodule/aes/internal.h +++ b/crypto/fipsmodule/aes/internal.h
@@ -26,9 +26,9 @@ // block128_f is the type of an AES block cipher implementation. // // Unlike upstream OpenSSL, it and the other functions in this file hard-code -// |AES_KEY|. It is undefined in C to call a function pointer with anything -// other than the original type. Thus we either must match |block128_f| to the -// type signature of |BCM_aes_encrypt| and friends or pass in |void*| wrapper +// `AES_KEY`. It is undefined in C to call a function pointer with anything +// other than the original type. Thus we either must match `block128_f` to the +// type signature of `BCM_aes_encrypt` and friends or pass in `void*` wrapper // functions. // // These functions are called exclusively with AES, so we use the former. @@ -39,9 +39,9 @@ typedef void (*ctr128_f)(const uint8_t *in, uint8_t *out, size_t blocks, const AES_KEY *key, const uint8_t ivec[16]); -// aes_ctr_set_key initialises |*aes_key| using |key_bytes| bytes from |key|, -// where |key_bytes| must either be 16, 24 or 32. If not NULL, |*out_block| is -// set to a function that encrypts single blocks. If not NULL, |*out_is_hwaes| +// aes_ctr_set_key initialises `*aes_key` using `key_bytes` bytes from `key`, +// where `key_bytes` must either be 16, 24 or 32. If not NULL, `*out_block` is +// set to a function that encrypts single blocks. If not NULL, `*out_is_hwaes` // is set to whether the hardware AES implementation was used. It returns a // function for optimised CTR-mode. ctr128_f aes_ctr_set_key(AES_KEY *aes_key, int *out_is_hwaes, @@ -104,8 +104,8 @@ const uint8_t ivec[16]); #if defined(OPENSSL_X86) || defined(OPENSSL_X86_64) -// On x86 and x86_64, |aes_hw_set_decrypt_key| is implemented in terms of -// |aes_hw_set_encrypt_key| and a conversion function. +// On x86 and x86_64, `aes_hw_set_decrypt_key` is implemented in terms of +// `aes_hw_set_encrypt_key` and a conversion function. extern "C" void aes_hw_encrypt_key_to_decrypt_key(AES_KEY *key); // There are two variants of this function, one which uses aeskeygenassist @@ -177,7 +177,7 @@ #if defined(BSAES) -// Note |bsaes_cbc_encrypt| requires |enc| to be zero. +// Note `bsaes_cbc_encrypt` requires `enc` to be zero. extern "C" void bsaes_cbc_encrypt(const uint8_t *in, uint8_t *out, size_t length, const AES_KEY *key, uint8_t ivec[16], int enc); @@ -264,8 +264,8 @@ inline void CRYPTO_xor16(uint8_t out[16], const uint8_t a[16], const uint8_t b[16]) { // TODO(davidben): Ideally we'd leave this to the compiler, which could use - // vector registers, etc. But the compiler doesn't know that |in| and |out| - // cannot partially alias. |restrict| is slightly two strict (we allow exact + // vector registers, etc. But the compiler doesn't know that `in` and `out` + // cannot partially alias. `restrict` is slightly two strict (we allow exact // aliasing), but perhaps in-place could be a separate function? static_assert(16 % sizeof(crypto_word_t) == 0, "block cannot be evenly divided into words"); @@ -279,12 +279,12 @@ // CTR. // CRYPTO_ctr128_encrypt_ctr32 encrypts (or decrypts, it's the same in CTR mode) -// |len| bytes from |in| to |out| using |block| in counter mode. There's no -// requirement that |len| be a multiple of any value and any partial blocks are -// stored in |ecount_buf| and |*num|, which must be zeroed before the initial -// call. The counter is a 128-bit, big-endian value in |ivec| and is +// `len` bytes from `in` to `out` using `block` in counter mode. There's no +// requirement that `len` be a multiple of any value and any partial blocks are +// stored in `ecount_buf` and `*num`, which must be zeroed before the initial +// call. The counter is a 128-bit, big-endian value in `ivec` and is // incremented by this function. If the counter overflows, it wraps around. -// |ctr| must be a function that performs CTR mode but only deals with the lower +// `ctr` must be a function that performs CTR mode but only deals with the lower // 32 bits of the counter. void CRYPTO_ctr128_encrypt_ctr32(const uint8_t *in, uint8_t *out, size_t len, const AES_KEY *key, uint8_t ivec[16], @@ -294,10 +294,10 @@ // GCM. // -// This API differs from the upstream API slightly. The |GCM128_CONTEXT| does -// not have a |key| pointer that points to the key as upstream's version does. -// Instead, every function takes a |key| parameter. This way |GCM128_CONTEXT| -// can be safely copied. Additionally, |gcm_key| is split into a separate +// This API differs from the upstream API slightly. The `GCM128_CONTEXT` does +// not have a `key` pointer that points to the key as upstream's version does. +// Instead, every function takes a `key` parameter. This way `GCM128_CONTEXT` +// can be safely copied. Additionally, `gcm_key` is split into a separate // struct. // gcm_impl_t specifies an assembly implementation of AES-GCM. @@ -312,12 +312,12 @@ typedef struct { uint64_t hi,lo; } u128; -// gmult_func multiplies |Xi| by the GCM key and writes the result back to -// |Xi|. +// gmult_func multiplies `Xi` by the GCM key and writes the result back to +// `Xi`. typedef void (*gmult_func)(uint8_t Xi[16], const u128 Htable[16]); -// ghash_func repeatedly multiplies |Xi| by the GCM key and adds in blocks from -// |inp|. The result is written back to |Xi| and the |len| argument must be a +// ghash_func repeatedly multiplies `Xi` by the GCM key and adds in blocks from +// `inp`. The result is written back to `Xi` and the `len` argument must be a // multiple of 16. typedef void (*ghash_func)(uint8_t Xi[16], const u128 Htable[16], const uint8_t *inp, size_t len); @@ -354,48 +354,48 @@ int crypto_gcm_clmul_enabled(); #endif -// CRYPTO_ghash_init writes a precomputed table of powers of |gcm_key| to -// |out_table| and sets |*out_mult| and |*out_hash| to (potentially hardware +// CRYPTO_ghash_init writes a precomputed table of powers of `gcm_key` to +// `out_table` and sets `*out_mult` and `*out_hash` to (potentially hardware // accelerated) functions for performing operations in the GHASH field. void CRYPTO_ghash_init(gmult_func *out_mult, ghash_func *out_hash, u128 out_table[16], const uint8_t gcm_key[16]); -// CRYPTO_gcm128_init_aes_key initialises |gcm_key| to with AES key |key|. +// CRYPTO_gcm128_init_aes_key initialises `gcm_key` to with AES key `key`. void CRYPTO_gcm128_init_aes_key(GCM128_KEY *gcm_key, const uint8_t *key, size_t key_bytes); -// CRYPTO_gcm128_init_ctx initializes |ctx| to encrypt with |key| and |iv|. +// CRYPTO_gcm128_init_ctx initializes `ctx` to encrypt with `key` and `iv`. void CRYPTO_gcm128_init_ctx(const GCM128_KEY *key, GCM128_CONTEXT *ctx, const uint8_t *iv, size_t iv_len); // CRYPTO_gcm128_aad adds to the authenticated data for an instance of GCM. -// This must be called before and data is encrypted. |key| must be the same -// value that was passed to |CRYPTO_gcm128_init_ctx|. It returns one on success +// This must be called before and data is encrypted. `key` must be the same +// value that was passed to `CRYPTO_gcm128_init_ctx`. It returns one on success // and zero otherwise. int CRYPTO_gcm128_aad(const GCM128_KEY *key, GCM128_CONTEXT *ctx, const uint8_t *aad, size_t aad_len); -// CRYPTO_gcm128_encrypt encrypts |len| bytes from |in| to |out|. |key| must be -// the same value that was passed to |CRYPTO_gcm128_init_ctx|. It returns one on +// CRYPTO_gcm128_encrypt encrypts `len` bytes from `in` to `out`. `key` must be +// the same value that was passed to `CRYPTO_gcm128_init_ctx`. It returns one on // success and zero otherwise. int CRYPTO_gcm128_encrypt(const GCM128_KEY *key, GCM128_CONTEXT *ctx, const uint8_t *in, uint8_t *out, size_t len); -// CRYPTO_gcm128_decrypt decrypts |len| bytes from |in| to |out|. |key| must be -// the same value that was passed to |CRYPTO_gcm128_init_ctx|. It returns one on +// CRYPTO_gcm128_decrypt decrypts `len` bytes from `in` to `out`. `key` must be +// the same value that was passed to `CRYPTO_gcm128_init_ctx`. It returns one on // success and zero otherwise. int CRYPTO_gcm128_decrypt(const GCM128_KEY *key, GCM128_CONTEXT *ctx, const uint8_t *in, uint8_t *out, size_t len); // CRYPTO_gcm128_finish calculates the authenticator and compares it against -// |len| bytes of |tag|. |key| must be the same value that was passed to -// |CRYPTO_gcm128_init_ctx|. It returns one on success and zero otherwise. +// `len` bytes of `tag`. `key` must be the same value that was passed to +// `CRYPTO_gcm128_init_ctx`. It returns one on success and zero otherwise. int CRYPTO_gcm128_finish(const GCM128_KEY *key, GCM128_CONTEXT *ctx, const uint8_t *tag, size_t len); -// CRYPTO_gcm128_tag calculates the authenticator and copies it into |tag|. -// The minimum of |len| and 16 bytes are copied into |tag|. |key| must be the -// same value that was passed to |CRYPTO_gcm128_init_ctx|. +// CRYPTO_gcm128_tag calculates the authenticator and copies it into `tag`. +// The minimum of `len` and 16 bytes are copied into `tag`. `key` must be the +// same value that was passed to `CRYPTO_gcm128_init_ctx`. void CRYPTO_gcm128_tag(const GCM128_KEY *key, GCM128_CONTEXT *ctx, uint8_t *tag, size_t len); @@ -528,7 +528,7 @@ typedef void (*cbc128_f)(const uint8_t *in, uint8_t *out, size_t len, const AES_KEY *key, uint8_t ivec[16], int enc); -// CRYPTO_cbc128_encrypt encrypts |len| bytes from |in| to |out| using the +// CRYPTO_cbc128_encrypt encrypts `len` bytes from `in` to `out` using the // given IV and block cipher in CBC mode. The input need not be a multiple of // 128 bits long, but the output will round up to the nearest 128 bit multiple, // zero padding the input if needed. The IV will be updated on return. @@ -536,10 +536,10 @@ const AES_KEY *key, uint8_t ivec[16], block128_f block); -// CRYPTO_cbc128_decrypt decrypts |len| bytes from |in| to |out| using the -// given IV and block cipher in CBC mode. If |len| is not a multiple of 128 +// CRYPTO_cbc128_decrypt decrypts `len` bytes from `in` to `out` using the +// given IV and block cipher in CBC mode. If `len` is not a multiple of 128 // bits then only that many bytes will be written, but a multiple of 128 bits -// is always read from |in|. The IV will be updated on return. +// is always read from `in`. The IV will be updated on return. void CRYPTO_cbc128_decrypt(const uint8_t *in, uint8_t *out, size_t len, const AES_KEY *key, uint8_t ivec[16], block128_f block); @@ -548,9 +548,9 @@ // OFB. // CRYPTO_ofb128_encrypt encrypts (or decrypts, it's the same with OFB mode) -// |len| bytes from |in| to |out| using |block| in OFB mode. There's no -// requirement that |len| be a multiple of any value and any partial blocks are -// stored in |ivec| and |*num|, the latter must be zero before the initial +// `len` bytes from `in` to `out` using `block` in OFB mode. There's no +// requirement that `len` be a multiple of any value and any partial blocks are +// stored in `ivec` and `*num`, the latter must be zero before the initial // call. void CRYPTO_ofb128_encrypt(const uint8_t *in, uint8_t *out, size_t len, const AES_KEY *key, uint8_t ivec[16], unsigned *num, @@ -559,24 +559,24 @@ // CFB. -// CRYPTO_cfb128_encrypt encrypts (or decrypts, if |enc| is zero) |len| bytes -// from |in| to |out| using |block| in CFB mode. There's no requirement that -// |len| be a multiple of any value and any partial blocks are stored in |ivec| -// and |*num|, the latter must be zero before the initial call. +// CRYPTO_cfb128_encrypt encrypts (or decrypts, if `enc` is zero) `len` bytes +// from `in` to `out` using `block` in CFB mode. There's no requirement that +// `len` be a multiple of any value and any partial blocks are stored in `ivec` +// and `*num`, the latter must be zero before the initial call. void CRYPTO_cfb128_encrypt(const uint8_t *in, uint8_t *out, size_t len, const AES_KEY *key, uint8_t ivec[16], unsigned *num, int enc, block128_f block); -// CRYPTO_cfb128_8_encrypt encrypts (or decrypts, if |enc| is zero) |len| bytes -// from |in| to |out| using |block| in CFB-8 mode. Prior to the first call -// |num| should be set to zero. +// CRYPTO_cfb128_8_encrypt encrypts (or decrypts, if `enc` is zero) `len` bytes +// from `in` to `out` using `block` in CFB-8 mode. Prior to the first call +// `num` should be set to zero. void CRYPTO_cfb128_8_encrypt(const uint8_t *in, uint8_t *out, size_t len, const AES_KEY *key, uint8_t ivec[16], unsigned *num, int enc, block128_f block); -// CRYPTO_cfb128_1_encrypt encrypts (or decrypts, if |enc| is zero) |len| bytes -// from |in| to |out| using |block| in CFB-1 mode. Prior to the first call -// |num| should be set to zero. +// CRYPTO_cfb128_1_encrypt encrypts (or decrypts, if `enc` is zero) `len` bytes +// from `in` to `out` using `block` in CFB-1 mode. Prior to the first call +// `num` should be set to zero. void CRYPTO_cfb128_1_encrypt(const uint8_t *in, uint8_t *out, size_t bits, const AES_KEY *key, uint8_t ivec[16], unsigned *num, int enc, block128_f block);
diff --git a/crypto/fipsmodule/bcm_interface.h b/crypto/fipsmodule/bcm_interface.h index db44e06..66f32aa 100644 --- a/crypto/fipsmodule/bcm_interface.h +++ b/crypto/fipsmodule/bcm_interface.h
@@ -73,48 +73,48 @@ #endif // BORINGSSL_FIPS -// BCM_rand_bytes is the same as the public |RAND_bytes| function, other +// BCM_rand_bytes is the same as the public `RAND_bytes` function, other // than returning a bcm_infallible status indicator. bcm_infallible BCM_rand_bytes(uint8_t *out, size_t out_len); -// BCM_rand_bytes_hwrng attempts to fill |out| with |len| bytes of entropy from +// BCM_rand_bytes_hwrng attempts to fill `out` with `len` bytes of entropy from // the CPU hardware random number generator if one is present. // bcm_status_approved is returned on success, and a failure status is // returned otherwise. bcm_status BCM_rand_bytes_hwrng(uint8_t *out, size_t len); // BCM_rand_bytes_with_additional_data samples from the RNG after mixing 32 -// bytes from |user_additional_data| in. +// bytes from `user_additional_data` in. bcm_infallible BCM_rand_bytes_with_additional_data( uint8_t *out, size_t out_len, const uint8_t user_additional_data[32]); // SHA-1 -// BCM_sha1_init initialises |sha|. +// BCM_sha1_init initialises `sha`. bcm_infallible BCM_sha1_init(SHA_CTX *sha); // SHA1_transform is a low-level function that performs a single, SHA-1 -// block transformation using the state from |sha| and |SHA_CBLOCK| bytes from -// |block|. +// block transformation using the state from `sha` and `SHA_CBLOCK` bytes from +// `block`. bcm_infallible BCM_sha1_transform(SHA_CTX *c, const uint8_t data[SHA_CBLOCK]); -// BCM_sha1_update adds |len| bytes from |data| to |sha|. +// BCM_sha1_update adds `len` bytes from `data` to `sha`. bcm_infallible BCM_sha1_update(SHA_CTX *c, const void *data, size_t len); -// BCM_sha1_final adds the final padding to |sha| and writes the resulting -// digest to |out|, which must have at least |SHA_DIGEST_LENGTH| bytes of space. +// BCM_sha1_final adds the final padding to `sha` and writes the resulting +// digest to `out`, which must have at least `SHA_DIGEST_LENGTH` bytes of space. bcm_infallible BCM_sha1_final(uint8_t out[SHA_DIGEST_LENGTH], SHA_CTX *c); -// BCM_fips_186_2_prf derives |out_len| bytes from |xkey| using the PRF +// BCM_fips_186_2_prf derives `out_len` bytes from `xkey` using the PRF // defined in FIPS 186-2, Appendix 3.1, with change notice 1 applied. The b // parameter is 160 and seed, XKEY, is also 160 bits. The optional XSEED user // input is all zeros. // // The PRF generates a sequence of 320-bit numbers. Each number is encoded as a -// 40-byte string in big-endian and then concatenated to form |out|. If -// |out_len| is not a multiple of 40, the result is truncated. This matches the +// 40-byte string in big-endian and then concatenated to form `out`. If +// `out_len` is not a multiple of 40, the result is truncated. This matches the // construction used in Section 7 of RFC 4186 and Section 7 of RFC 4187. // // This PRF is based on SHA-1, a weak hash function, and should not be used @@ -126,14 +126,14 @@ // SHA-224 -// BCM_sha224_unit initialises |sha|. +// BCM_sha224_unit initialises `sha`. bcm_infallible BCM_sha224_init(SHA256_CTX *sha); -// BCM_sha224_update adds |len| bytes from |data| to |sha|. +// BCM_sha224_update adds `len` bytes from `data` to `sha`. bcm_infallible BCM_sha224_update(SHA256_CTX *sha, const void *data, size_t len); -// BCM_sha224_final adds the final padding to |sha| and writes the resulting -// digest to |out|, which must have at least |SHA224_DIGEST_LENGTH| bytes of +// BCM_sha224_final adds the final padding to `sha` and writes the resulting +// digest to `out`, which must have at least `SHA224_DIGEST_LENGTH` bytes of // space. It aborts on programmer error. bcm_infallible BCM_sha224_final(uint8_t out[SHA224_DIGEST_LENGTH], SHA256_CTX *sha); @@ -141,27 +141,27 @@ // SHA-256 -// BCM_sha256_init initialises |sha|. +// BCM_sha256_init initialises `sha`. bcm_infallible BCM_sha256_init(SHA256_CTX *sha); -// BCM_sha256_update adds |len| bytes from |data| to |sha|. +// BCM_sha256_update adds `len` bytes from `data` to `sha`. bcm_infallible BCM_sha256_update(SHA256_CTX *sha, const void *data, size_t len); -// BCM_sha256_final adds the final padding to |sha| and writes the resulting -// digest to |out|, which must have at least |SHA256_DIGEST_LENGTH| bytes of +// BCM_sha256_final adds the final padding to `sha` and writes the resulting +// digest to `out`, which must have at least `SHA256_DIGEST_LENGTH` bytes of // space. It aborts on programmer error. bcm_infallible BCM_sha256_final(uint8_t out[SHA256_DIGEST_LENGTH], SHA256_CTX *sha); // BCM_sha256_transform is a low-level function that performs a single, SHA-256 -// block transformation using the state from |sha| and |SHA256_CBLOCK| bytes -// from |block|. +// block transformation using the state from `sha` and `SHA256_CBLOCK` bytes +// from `block`. bcm_infallible BCM_sha256_transform(SHA256_CTX *sha, const uint8_t block[SHA256_CBLOCK]); -// BCM_sha256_transform_blocks is a low-level function that takes |num_blocks| * -// |SHA256_CBLOCK| bytes of data and performs SHA-256 transforms on it to update -// |state|. +// BCM_sha256_transform_blocks is a low-level function that takes `num_blocks` * +// `SHA256_CBLOCK` bytes of data and performs SHA-256 transforms on it to update +// `state`. bcm_infallible BCM_sha256_transform_blocks(uint32_t state[8], const uint8_t *data, size_t num_blocks); @@ -169,14 +169,14 @@ // SHA-384. -// BCM_sha384_init initialises |sha|. +// BCM_sha384_init initialises `sha`. bcm_infallible BCM_sha384_init(SHA512_CTX *sha); -// BCM_sha384_update adds |len| bytes from |data| to |sha|. +// BCM_sha384_update adds `len` bytes from `data` to `sha`. bcm_infallible BCM_sha384_update(SHA512_CTX *sha, const void *data, size_t len); -// BCM_sha384_final adds the final padding to |sha| and writes the resulting -// digest to |out|, which must have at least |SHA384_DIGEST_LENGTH| bytes of +// BCM_sha384_final adds the final padding to `sha` and writes the resulting +// digest to `out`, which must have at least `SHA384_DIGEST_LENGTH` bytes of // space. It may abort on programmer error. bcm_infallible BCM_sha384_final(uint8_t out[SHA384_DIGEST_LENGTH], SHA512_CTX *sha); @@ -184,21 +184,21 @@ // SHA-512. -// BCM_sha512_init initialises |sha|. +// BCM_sha512_init initialises `sha`. bcm_infallible BCM_sha512_init(SHA512_CTX *sha); -// BCM_sha512_update adds |len| bytes from |data| to |sha|. +// BCM_sha512_update adds `len` bytes from `data` to `sha`. bcm_infallible BCM_sha512_update(SHA512_CTX *sha, const void *data, size_t len); -// BCM_sha512_final adds the final padding to |sha| and writes the resulting -// digest to |out|, which must have at least |SHA512_DIGEST_LENGTH| bytes of +// BCM_sha512_final adds the final padding to `sha` and writes the resulting +// digest to `out`, which must have at least `SHA512_DIGEST_LENGTH` bytes of // space. bcm_infallible BCM_sha512_final(uint8_t out[SHA512_DIGEST_LENGTH], SHA512_CTX *sha); // BCM_sha512_transform is a low-level function that performs a single, SHA-512 -// block transformation using the state from |sha| and |SHA512_CBLOCK| bytes -// from |block|. +// block transformation using the state from `sha` and `SHA512_CBLOCK` bytes +// from `block`. bcm_infallible BCM_sha512_transform(SHA512_CTX *sha, const uint8_t block[SHA512_CBLOCK]); @@ -207,15 +207,15 @@ // // See https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf section 5.3.6 -// BCM_sha512_256_init initialises |sha|. +// BCM_sha512_256_init initialises `sha`. bcm_infallible BCM_sha512_256_init(SHA512_CTX *sha); -// BCM_sha512_256_update adds |len| bytes from |data| to |sha|. +// BCM_sha512_256_update adds `len` bytes from `data` to `sha`. bcm_infallible BCM_sha512_256_update(SHA512_CTX *sha, const void *data, size_t len); -// BCM_sha512_256_final adds the final padding to |sha| and writes the resulting -// digest to |out|, which must have at least |SHA512_256_DIGEST_LENGTH| bytes of +// BCM_sha512_256_final adds the final padding to `sha` and writes the resulting +// digest to `out`, which must have at least `SHA512_256_DIGEST_LENGTH` bytes of // space. It may abort on programmer error. bcm_infallible BCM_sha512_256_final(uint8_t out[SHA512_256_DIGEST_LENGTH], SHA512_CTX *sha); @@ -244,7 +244,7 @@ OPENSSL_EXPORT bcm_status BCM_mldsa65_public_from_private( MLDSA65_public_key *out_public_key, const MLDSA65_private_key *private_key); -// BCM_mldsa65_public_of_private returns the public half of |private_key|. +// BCM_mldsa65_public_of_private returns the public half of `private_key`. const MLDSA65_public_key *BCM_mldsa65_public_of_private( const MLDSA65_private_key *private_key); @@ -299,7 +299,7 @@ // BCM_mldsa65_generate_key_external_entropy generates a public/private key pair // using the given seed, writes the encoded public key to -// |out_encoded_public_key| and sets |out_private_key| to the private key. +// `out_encoded_public_key` and sets `out_private_key` to the private key. OPENSSL_EXPORT bcm_status BCM_mldsa65_generate_key_external_entropy( uint8_t out_encoded_public_key[MLDSA65_PUBLIC_KEY_BYTES], MLDSA65_private_key *out_private_key, @@ -310,11 +310,11 @@ MLDSA65_private_key *out_private_key, const uint8_t entropy[MLDSA_SEED_BYTES]); -// BCM_mldsa5_sign_internal signs |msg| using |private_key| and writes the -// signature to |out_encoded_signature|. The |context_prefix| and |context| are -// prefixed to the message, in that order, before signing. The |randomizer| +// BCM_mldsa5_sign_internal signs `msg` using `private_key` and writes the +// signature to `out_encoded_signature`. The `context_prefix` and `context` are +// prefixed to the message, in that order, before signing. The `randomizer` // value can be set to zero bytes in order to make a deterministic signature, or -// else filled with entropy for the usual |MLDSA_sign| behavior. +// else filled with entropy for the usual `MLDSA_sign` behavior. OPENSSL_EXPORT bcm_status BCM_mldsa65_sign_internal( uint8_t out_encoded_signature[MLDSA65_SIGNATURE_BYTES], const MLDSA65_private_key *private_key, const uint8_t *msg, size_t msg_len, @@ -328,8 +328,8 @@ const uint8_t msg_rep[MLDSA_MU_BYTES], const uint8_t randomizer[BCM_MLDSA_SIGNATURE_RANDOMIZER_BYTES]); -// BCM_mldsa5_verify_internal verifies that |encoded_signature| is a valid -// signature of |msg| by |public_key|. The |context_prefix| and |context| are +// BCM_mldsa5_verify_internal verifies that `encoded_signature` is a valid +// signature of `msg` by `public_key`. The `context_prefix` and `context` are // prefixed to the message before verification, in that order. OPENSSL_EXPORT bcm_status BCM_mldsa65_verify_internal( const MLDSA65_public_key *public_key, @@ -337,12 +337,12 @@ const uint8_t *msg, size_t msg_len, const uint8_t *context_prefix, size_t context_prefix_len, const uint8_t *context, size_t context_len); -// BCM_mldsa65_marshal_private_key serializes |private_key| to |out| in the +// BCM_mldsa65_marshal_private_key serializes `private_key` to `out` in the // NIST format for ML-DSA-65 private keys. OPENSSL_EXPORT bcm_status BCM_mldsa65_marshal_private_key( CBB *out, const MLDSA65_private_key *private_key); -// BCM_mldsa65_public_keys_equal returns one if |a| and |b| are equal and zero +// BCM_mldsa65_public_keys_equal returns one if `a` and `b` are equal and zero // otherwise. int BCM_mldsa65_public_keys_equal(const MLDSA65_public_key *a, const MLDSA65_public_key *b); @@ -362,7 +362,7 @@ OPENSSL_EXPORT bcm_status BCM_mldsa87_public_from_private( MLDSA87_public_key *out_public_key, const MLDSA87_private_key *private_key); -// BCM_mldsa87_public_of_private returns the public half of |private_key|. +// BCM_mldsa87_public_of_private returns the public half of `private_key`. const MLDSA87_public_key *BCM_mldsa87_public_of_private( const MLDSA87_private_key *private_key); @@ -417,7 +417,7 @@ // BCM_mldsa87_generate_key_external_entropy generates a public/private key pair // using the given seed, writes the encoded public key to -// |out_encoded_public_key| and sets |out_private_key| to the private key. +// `out_encoded_public_key` and sets `out_private_key` to the private key. OPENSSL_EXPORT bcm_status BCM_mldsa87_generate_key_external_entropy( uint8_t out_encoded_public_key[MLDSA87_PUBLIC_KEY_BYTES], MLDSA87_private_key *out_private_key, @@ -428,11 +428,11 @@ MLDSA87_private_key *out_private_key, const uint8_t entropy[MLDSA_SEED_BYTES]); -// BCM_mldsa87_sign_internal signs |msg| using |private_key| and writes the -// signature to |out_encoded_signature|. The |context_prefix| and |context| are -// prefixed to the message, in that order, before signing. The |randomizer| +// BCM_mldsa87_sign_internal signs `msg` using `private_key` and writes the +// signature to `out_encoded_signature`. The `context_prefix` and `context` are +// prefixed to the message, in that order, before signing. The `randomizer` // value can be set to zero bytes in order to make a deterministic signature, or -// else filled with entropy for the usual |MLDSA_sign| behavior. +// else filled with entropy for the usual `MLDSA_sign` behavior. OPENSSL_EXPORT bcm_status BCM_mldsa87_sign_internal( uint8_t out_encoded_signature[MLDSA87_SIGNATURE_BYTES], const MLDSA87_private_key *private_key, const uint8_t *msg, size_t msg_len, @@ -446,8 +446,8 @@ const uint8_t msg_rep[MLDSA_MU_BYTES], const uint8_t randomizer[BCM_MLDSA_SIGNATURE_RANDOMIZER_BYTES]); -// BCM_mldsa87_verify_internal verifies that |encoded_signature| is a valid -// signature of |msg| by |public_key|. The |context_prefix| and |context| are +// BCM_mldsa87_verify_internal verifies that `encoded_signature` is a valid +// signature of `msg` by `public_key`. The `context_prefix` and `context` are // prefixed to the message before verification, in that order. OPENSSL_EXPORT bcm_status BCM_mldsa87_verify_internal( const MLDSA87_public_key *public_key, @@ -455,12 +455,12 @@ const uint8_t *msg, size_t msg_len, const uint8_t *context_prefix, size_t context_prefix_len, const uint8_t *context, size_t context_len); -// BCM_mldsa87_marshal_private_key serializes |private_key| to |out| in the +// BCM_mldsa87_marshal_private_key serializes `private_key` to `out` in the // NIST format for ML-DSA-87 private keys. OPENSSL_EXPORT bcm_status BCM_mldsa87_marshal_private_key( CBB *out, const MLDSA87_private_key *private_key); -// BCM_mldsa87_public_keys_equal returns one if |a| and |b| are equal and zero +// BCM_mldsa87_public_keys_equal returns one if `a` and `b` are equal and zero // otherwise. int BCM_mldsa87_public_keys_equal(const MLDSA87_public_key *a, const MLDSA87_public_key *b); @@ -479,7 +479,7 @@ OPENSSL_EXPORT bcm_status BCM_mldsa44_public_from_private( MLDSA44_public_key *out_public_key, const MLDSA44_private_key *private_key); -// BCM_mldsa44_public_of_private returns the public half of |private_key|. +// BCM_mldsa44_public_of_private returns the public half of `private_key`. const MLDSA44_public_key *BCM_mldsa44_public_of_private( const MLDSA44_private_key *private_key); @@ -534,7 +534,7 @@ // BCM_mldsa44_generate_key_external_entropy generates a public/private key pair // using the given seed, writes the encoded public key to -// |out_encoded_public_key| and sets |out_private_key| to the private key. +// `out_encoded_public_key` and sets `out_private_key` to the private key. OPENSSL_EXPORT bcm_status BCM_mldsa44_generate_key_external_entropy( uint8_t out_encoded_public_key[MLDSA44_PUBLIC_KEY_BYTES], MLDSA44_private_key *out_private_key, @@ -545,11 +545,11 @@ MLDSA44_private_key *out_private_key, const uint8_t entropy[MLDSA_SEED_BYTES]); -// BCM_mldsa44_sign_internal signs |msg| using |private_key| and writes the -// signature to |out_encoded_signature|. The |context_prefix| and |context| are -// prefixed to the message, in that order, before signing. The |randomizer| +// BCM_mldsa44_sign_internal signs `msg` using `private_key` and writes the +// signature to `out_encoded_signature`. The `context_prefix` and `context` are +// prefixed to the message, in that order, before signing. The `randomizer` // value can be set to zero bytes in order to make a deterministic signature, or -// else filled with entropy for the usual |MLDSA_sign| behavior. +// else filled with entropy for the usual `MLDSA_sign` behavior. OPENSSL_EXPORT bcm_status BCM_mldsa44_sign_internal( uint8_t out_encoded_signature[MLDSA44_SIGNATURE_BYTES], const MLDSA44_private_key *private_key, const uint8_t *msg, size_t msg_len, @@ -563,8 +563,8 @@ const uint8_t msg_rep[MLDSA_MU_BYTES], const uint8_t randomizer[BCM_MLDSA_SIGNATURE_RANDOMIZER_BYTES]); -// BCM_mldsa44_verify_internal verifies that |encoded_signature| is a valid -// signature of |msg| by |public_key|. The |context_prefix| and |context| are +// BCM_mldsa44_verify_internal verifies that `encoded_signature` is a valid +// signature of `msg` by `public_key`. The `context_prefix` and `context` are // prefixed to the message before verification, in that order. OPENSSL_EXPORT bcm_status BCM_mldsa44_verify_internal( const MLDSA44_public_key *public_key, @@ -572,12 +572,12 @@ const uint8_t *msg, size_t msg_len, const uint8_t *context_prefix, size_t context_prefix_len, const uint8_t *context, size_t context_len); -// BCM_mldsa44_marshal_private_key serializes |private_key| to |out| in the +// BCM_mldsa44_marshal_private_key serializes `private_key` to `out` in the // NIST format for ML-DSA-44 private keys. OPENSSL_EXPORT bcm_status BCM_mldsa44_marshal_private_key( CBB *out, const MLDSA44_private_key *private_key); -// BCM_mldsa44_public_keys_equal returns one if |a| and |b| are equal and zero +// BCM_mldsa44_public_keys_equal returns one if `a` and `b` are equal and zero // otherwise. int BCM_mldsa44_public_keys_equal(const MLDSA44_public_key *a, const MLDSA44_public_key *b); @@ -594,11 +594,11 @@ #define BCM_MLKEM_ENCAP_ENTROPY 32 // BCM_MLKEM768_PRIVATE_KEY_BYTES is the length of the data produced by -// |BCM_mlkem768_marshal_private_key|. +// `BCM_mlkem768_marshal_private_key`. #define BCM_MLKEM768_PRIVATE_KEY_BYTES 2400 // BCM_MLKEM1024_PRIVATE_KEY_BYTES is the length of the data produced by -// |BCM_mlkem1024_marshal_private_key|. +// `BCM_mlkem1024_marshal_private_key`. #define BCM_MLKEM1024_PRIVATE_KEY_BYTES 3168 OPENSSL_EXPORT bcm_infallible BCM_mlkem768_generate_key( @@ -638,7 +638,7 @@ OPENSSL_EXPORT bcm_status BCM_mlkem768_marshal_public_key( CBB *out, const MLKEM768_public_key *public_key); -// BCM_mlkem768_public_keys_equal returns one if |a| and |b| are equal and zero +// BCM_mlkem768_public_keys_equal returns one if `a` and `b` are equal and zero // otherwise. int BCM_mlkem768_public_keys_equal(const MLKEM768_public_key *a, const MLKEM768_public_key *b); @@ -647,37 +647,37 @@ BCM_mlkem768_parse_public_key(MLKEM768_public_key *out_public_key, CBS *in); // BCM_mlkem768_parse_private_key parses a private key, in NIST's format for -// private keys, from |in| and writes the result to |out_private_key|. It +// private keys, from `in` and writes the result to `out_private_key`. It // returns one on success or zero on parse error or if there are trailing bytes -// in |in|. This format is verbose and should be avoided. Private keys should be -// stored as seeds and parsed using |BCM_mlkem768_private_key_from_seed|. +// in `in`. This format is verbose and should be avoided. Private keys should be +// stored as seeds and parsed using `BCM_mlkem768_private_key_from_seed`. OPENSSL_EXPORT bcm_status BCM_mlkem768_parse_private_key(MLKEM768_private_key *out_private_key, CBS *in); // BCM_mlkem768_generate_key_external_seed is a deterministic function to create // a pair of ML-KEM-768 keys, using the supplied seed. The seed needs to be // uniformly random. This function should only be used for tests; regular -// callers should use the non-deterministic |BCM_mlkem768_generate_key| +// callers should use the non-deterministic `BCM_mlkem768_generate_key` // directly. OPENSSL_EXPORT bcm_infallible BCM_mlkem768_generate_key_external_seed( uint8_t out_encoded_public_key[MLKEM768_PUBLIC_KEY_BYTES], MLKEM768_private_key *out_private_key, const uint8_t seed[MLKEM_SEED_BYTES]); -// BCM_mlkem768_encap_external_entropy behaves like |MLKEM768_encap|, but uses -// |MLKEM_ENCAP_ENTROPY| bytes of |entropy| for randomization. The decapsulating -// side will be able to recover |entropy| in full. This function should only be +// BCM_mlkem768_encap_external_entropy behaves like `MLKEM768_encap`, but uses +// `MLKEM_ENCAP_ENTROPY` bytes of `entropy` for randomization. The decapsulating +// side will be able to recover `entropy` in full. This function should only be // used for tests, regular callers should use the non-deterministic -// |BCM_mlkem768_encap| directly. +// `BCM_mlkem768_encap` directly. OPENSSL_EXPORT bcm_infallible BCM_mlkem768_encap_external_entropy( uint8_t out_ciphertext[MLKEM768_CIPHERTEXT_BYTES], uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES], const MLKEM768_public_key *public_key, const uint8_t entropy[BCM_MLKEM_ENCAP_ENTROPY]); -// BCM_mlkem768_marshal_private_key serializes |private_key| to |out| in the +// BCM_mlkem768_marshal_private_key serializes `private_key` to `out` in the // NIST format for ML-KEM-768 private keys. (Note that one can also save just -// the seed value produced by |BCM_mlkem768_generate_key|, which is +// the seed value produced by `BCM_mlkem768_generate_key`, which is // significantly smaller.) OPENSSL_EXPORT bcm_status BCM_mlkem768_marshal_private_key( CBB *out, const MLKEM768_private_key *private_key); @@ -719,7 +719,7 @@ OPENSSL_EXPORT bcm_status BCM_mlkem1024_marshal_public_key( CBB *out, const MLKEM1024_public_key *public_key); -// BCM_mlkem1024_public_keys_equal returns one if |a| and |b| are equal and zero +// BCM_mlkem1024_public_keys_equal returns one if `a` and `b` are equal and zero // otherwise. int BCM_mlkem1024_public_keys_equal(const MLKEM1024_public_key *a, const MLKEM1024_public_key *b); @@ -728,37 +728,37 @@ BCM_mlkem1024_parse_public_key(MLKEM1024_public_key *out_public_key, CBS *in); // BCM_mlkem1024_parse_private_key parses a private key, in NIST's format for -// private keys, from |in| and writes the result to |out_private_key|. It +// private keys, from `in` and writes the result to `out_private_key`. It // returns one on success or zero on parse error or if there are trailing bytes -// in |in|. This format is verbose and should be avoided. Private keys should be -// stored as seeds and parsed using |BCM_mlkem1024_private_key_from_seed|. +// in `in`. This format is verbose and should be avoided. Private keys should be +// stored as seeds and parsed using `BCM_mlkem1024_private_key_from_seed`. OPENSSL_EXPORT bcm_status BCM_mlkem1024_parse_private_key( MLKEM1024_private_key *out_private_key, CBS *in); // BCM_mlkem1024_generate_key_external_seed is a deterministic function to // create a pair of ML-KEM-1024 keys, using the supplied seed. The seed needs to // be uniformly random. This function should only be used for tests, regular -// callers should use the non-deterministic |BCM_mlkem1024_generate_key| +// callers should use the non-deterministic `BCM_mlkem1024_generate_key` // directly. OPENSSL_EXPORT bcm_infallible BCM_mlkem1024_generate_key_external_seed( uint8_t out_encoded_public_key[MLKEM1024_PUBLIC_KEY_BYTES], MLKEM1024_private_key *out_private_key, const uint8_t seed[MLKEM_SEED_BYTES]); -// BCM_mlkem1024_encap_external_entropy behaves like |MLKEM1024_encap|, but uses -// |MLKEM_ENCAP_ENTROPY| bytes of |entropy| for randomization. The -// decapsulating side will be able to recover |entropy| in full. This function +// BCM_mlkem1024_encap_external_entropy behaves like `MLKEM1024_encap`, but uses +// `MLKEM_ENCAP_ENTROPY` bytes of `entropy` for randomization. The +// decapsulating side will be able to recover `entropy` in full. This function // should only be used for tests, regular callers should use the -// non-deterministic |BCM_mlkem1024_encap| directly. +// non-deterministic `BCM_mlkem1024_encap` directly. OPENSSL_EXPORT bcm_infallible BCM_mlkem1024_encap_external_entropy( uint8_t out_ciphertext[MLKEM1024_CIPHERTEXT_BYTES], uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES], const MLKEM1024_public_key *public_key, const uint8_t entropy[BCM_MLKEM_ENCAP_ENTROPY]); -// BCM_mlkem1024_marshal_private_key serializes |private_key| to |out| in the +// BCM_mlkem1024_marshal_private_key serializes `private_key` to `out` in the // NIST format for ML-KEM-1024 private keys. (Note that one can also save just -// the seed value produced by |BCM_mlkem1024_generate_key|, which is +// the seed value produced by `BCM_mlkem1024_generate_key`, which is // significantly smaller.) OPENSSL_EXPORT bcm_status BCM_mlkem1024_marshal_private_key( CBB *out, const MLKEM1024_private_key *private_key); @@ -790,8 +790,8 @@ #define BCM_SLHDSA_SHAKE_256F_SIGNATURE_BYTES 49856 // BCM_slhdsa_sha2_128s_generate_key_from_seed generates an SLH-DSA-SHA2-128s -// key pair from a 48-byte seed and writes the result to |out_public_key| and -// |out_secret_key|. +// key pair from a 48-byte seed and writes the result to `out_public_key` and +// `out_secret_key`. OPENSSL_EXPORT bcm_infallible BCM_slhdsa_sha2_128s_generate_key_from_seed( uint8_t out_public_key[BCM_SLHDSA_SHA2_128S_PUBLIC_KEY_BYTES], uint8_t out_secret_key[BCM_SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES], @@ -815,11 +815,11 @@ uint8_t out_secret_key[BCM_SLHDSA_SHAKE_256F_PRIVATE_KEY_BYTES], const uint8_t seed[3 * BCM_SLHDSA_SHAKE_256F_N]); -// BCM_slhdsa_sha2_128s_sign_internal acts like |SLHDSA_SHA2_128S_sign| but +// BCM_slhdsa_sha2_128s_sign_internal acts like `SLHDSA_SHA2_128S_sign` but // accepts an explicit entropy input, which can be PK.seed (bytes 32..48 of // the private key) to generate deterministic signatures. It also takes the // input message in three parts so that the "internal" version of the signing -// function, from section 9.2, can be implemented. The |header| argument may be +// function, from section 9.2, can be implemented. The `header` argument may be // NULL to omit it. OPENSSL_EXPORT bcm_infallible BCM_slhdsa_sha2_128s_sign_internal( uint8_t out_signature[BCM_SLHDSA_SHA2_128S_SIGNATURE_BYTES], @@ -835,9 +835,9 @@ size_t context_len, const uint8_t *msg, size_t msg_len, const uint8_t entropy[BCM_SLHDSA_SHAKE_256F_N]); -// BCM_slhdsa_sha2_128s_verify_internal acts like |SLHDSA_SHA2_128S_verify| but +// BCM_slhdsa_sha2_128s_verify_internal acts like `SLHDSA_SHA2_128S_verify` but // takes the input message in three parts so that the "internal" version of the -// verification function, from section 9.3, can be implemented. The |header| +// verification function, from section 9.3, can be implemented. The `header` // argument may be NULL to omit it. OPENSSL_EXPORT bcm_status BCM_slhdsa_sha2_128s_verify_internal( const uint8_t *signature, size_t signature_len, @@ -926,24 +926,24 @@ // AES -// BCM_aes_encrypt encrypts a single block from |in| to |out| with |key|. The -// |in| and |out| pointers may overlap. +// BCM_aes_encrypt encrypts a single block from `in` to `out` with `key`. The +// `in` and `out` pointers may overlap. bcm_infallible BCM_aes_encrypt(const uint8_t *in, uint8_t *out, const AES_KEY *key); -// BCM_aes_decrypt decrypts a single block from |in| to |out| with |key|. The -// |in| and |out| pointers may overlap. +// BCM_aes_decrypt decrypts a single block from `in` to `out` with `key`. The +// `in` and `out` pointers may overlap. bcm_infallible BCM_aes_decrypt(const uint8_t *in, uint8_t *out, const AES_KEY *key); -// BCM_aes_set_encrypt_key configures |aeskey| to encrypt with the |bits|-bit -// key, |key|. |key| must point to |bits|/8 bytes. It will return failure if -// |bits| is an invalid AES key size. +// BCM_aes_set_encrypt_key configures `aeskey` to encrypt with the `bits`-bit +// key, `key`. `key` must point to `bits`/8 bytes. It will return failure if +// `bits` is an invalid AES key size. bcm_status BCM_aes_set_encrypt_key(const uint8_t *key, unsigned bits, AES_KEY *aeskey); -// BCM_aes_set_decrypt_key configures |aeskey| to decrypt with the |bits|-bit -// key, |key|. |key| must point to |bits|/8 bytes. It will return failure if -// |bits| is an invalid AES key size. +// BCM_aes_set_decrypt_key configures `aeskey` to decrypt with the `bits`-bit +// key, `key`. `key` must point to `bits`/8 bytes. It will return failure if +// `bits` is an invalid AES key size. bcm_status BCM_aes_set_decrypt_key(const uint8_t *key, unsigned bits, AES_KEY *aeskey);
diff --git a/crypto/fipsmodule/bn/internal.h b/crypto/fipsmodule/bn/internal.h index 486fae1..2fa8ebb 100644 --- a/crypto/fipsmodule/bn/internal.h +++ b/crypto/fipsmodule/bn/internal.h
@@ -64,7 +64,7 @@ #define BN_MASK2h1 (0xffff8000UL) #define BN_MASK2h (0xffff0000UL) // On some 32-bit platforms, Montgomery multiplication is done using 64-bit -// arithmetic with SIMD instructions. On such platforms, |BN_MONT_CTX::n0| +// arithmetic with SIMD instructions. On such platforms, `BN_MONT_CTX::n0` // needs to be two words long. Only certain 32-bit platforms actually make use // of n0[1] and shorter R value would suffice for the others. However, // currently only the assembly files know which is which. @@ -81,7 +81,7 @@ #define BN_CAN_USE_INLINE_ASM #endif -// MOD_EXP_CTIME_ALIGN is the alignment needed for |BN_mod_exp_mont_consttime|'s +// MOD_EXP_CTIME_ALIGN is the alignment needed for `BN_mod_exp_mont_consttime`'s // tables. // // TODO(davidben): Historically, this alignment came from cache line @@ -91,8 +91,8 @@ // requirements. #define MOD_EXP_CTIME_ALIGN 64 -// MOD_EXP_CTIME_STORAGE_LEN is the number of |BN_ULONG|s needed for the -// |BN_mod_exp_mont_consttime| stack-allocated storage buffer. The buffer is +// MOD_EXP_CTIME_STORAGE_LEN is the number of `BN_ULONG`s needed for the +// `BN_mod_exp_mont_consttime` stack-allocated storage buffer. The buffer is // just the right size for the RSAZ and is about ~1KB larger than what's // necessary (4480 bytes) for 1024-bit inputs. #define MOD_EXP_CTIME_STORAGE_LEN \ @@ -105,64 +105,64 @@ } // bn_minimal_width returns the minimal number of words needed to represent -// |bn|. +// `bn`. int bn_minimal_width(const BIGNUM *bn); -// bn_set_minimal_width sets |bn->width| to |bn_minimal_width(bn)|. If |bn| is -// zero, |bn->neg| is set to zero. +// bn_set_minimal_width sets `bn->width` to `bn_minimal_width(bn)`. If `bn` is +// zero, `bn->neg` is set to zero. void bn_set_minimal_width(BIGNUM *bn); -// bn_wexpand ensures that |bn| has at least |words| works of space without +// bn_wexpand ensures that `bn` has at least `words` works of space without // altering its value. It returns one on success or zero on allocation // failure. int bn_wexpand(BIGNUM *bn, size_t words); -// bn_expand acts the same as |bn_wexpand|, but takes a number of bits rather +// bn_expand acts the same as `bn_wexpand`, but takes a number of bits rather // than a number of words. int bn_expand(BIGNUM *bn, size_t bits); -// bn_resize_words adjusts |bn->width| to be |words|. It returns one on success -// and zero on allocation error or if |bn|'s value is too large. +// bn_resize_words adjusts `bn->width` to be `words`. It returns one on success +// and zero on allocation error or if `bn`'s value is too large. OPENSSL_EXPORT int bn_resize_words(BIGNUM *bn, size_t words); -// bn_select_words sets |r| to |a| if |mask| is all ones or |b| if |mask| is +// bn_select_words sets `r` to `a` if `mask` is all ones or `b` if `mask` is // all zeros. void bn_select_words(BN_ULONG *r, BN_ULONG mask, const BN_ULONG *a, const BN_ULONG *b, size_t num); -// bn_set_words sets |bn| to the value encoded in the |num| words in |words|, +// bn_set_words sets `bn` to the value encoded in the `num` words in `words`, // least significant word first. int bn_set_words(BIGNUM *bn, const BN_ULONG *words, size_t num); -// bn_set_static_words acts like |bn_set_words|, but doesn't copy the data. A -// flag is set on |bn| so that |BN_free| won't attempt to free the data. +// bn_set_static_words acts like `bn_set_words`, but doesn't copy the data. A +// flag is set on `bn` so that `BN_free` won't attempt to free the data. // -// The |STATIC_BIGNUM| macro is probably a better solution for this outside of +// The `STATIC_BIGNUM` macro is probably a better solution for this outside of // the FIPS module. Inside of the FIPS module that macro generates rel.ro data, // which doesn't work with FIPS requirements. void bn_set_static_words(BIGNUM *bn, const BN_ULONG *words, size_t num); -// bn_fits_in_words returns one if |bn| may be represented in |num| words, plus +// bn_fits_in_words returns one if `bn` may be represented in `num` words, plus // a sign bit, and zero otherwise. int bn_fits_in_words(const BIGNUM *bn, size_t num); -// bn_copy_words copies the value of |bn| to |out| and returns one if the value -// is representable in |num| words. Otherwise, it returns zero. +// bn_copy_words copies the value of `bn` to `out` and returns one if the value +// is representable in `num` words. Otherwise, it returns zero. int bn_copy_words(BN_ULONG *out, size_t num, const BIGNUM *bn); -// bn_assert_fits_in_bytes asserts that |bn| fits in |num| bytes. This is a +// bn_assert_fits_in_bytes asserts that `bn` fits in `num` bytes. This is a // no-op in release builds, but triggers an assert in debug builds, and // declassifies all bytes which are therefore known to be zero in constant-time // validation. void bn_assert_fits_in_bytes(const BIGNUM *bn, size_t num); -// bn_secret marks |bn|'s contents, but not its width or sign, as secret. See -// |CONSTTIME_SECRET| for details. +// bn_secret marks `bn`'s contents, but not its width or sign, as secret. See +// `CONSTTIME_SECRET` for details. inline void bn_secret(BIGNUM *bn) { CONSTTIME_SECRET(bn->d, bn->width * sizeof(BN_ULONG)); } -// bn_declassify marks |bn|'s value as public. See |CONSTTIME_DECLASSIFY| for +// bn_declassify marks `bn`'s value as public. See `CONSTTIME_DECLASSIFY` for // details. inline void bn_declassify(BIGNUM *bn) { CONSTTIME_DECLASSIFY(bn->d, bn->width * sizeof(BN_ULONG)); @@ -186,9 +186,9 @@ #define BN_ADD_ASM #endif -// bn_mul_add_words multiples |ap| by |w|, adds the result to |rp|, and places -// the result in |rp|. |ap| and |rp| must both be |num| words long. It returns -// the carry word of the operation. |ap| and |rp| may be equal but otherwise may +// bn_mul_add_words multiples `ap` by `w`, adds the result to `rp`, and places +// the result in `rp`. `ap` and `rp` must both be `num` words long. It returns +// the carry word of the operation. `ap` and `rp` may be equal but otherwise may // not alias. #if defined(BN_MUL_ASM) extern "C" @@ -196,30 +196,30 @@ BN_ULONG bn_mul_add_words(BN_ULONG *rp, const BN_ULONG *ap, size_t num, BN_ULONG w); -// bn_mul_words multiples |ap| by |w| and places the result in |rp|. |ap| and -// |rp| must both be |num| words long. It returns the carry word of the -// operation. |ap| and |rp| may be equal but otherwise may not alias. +// bn_mul_words multiples `ap` by `w` and places the result in `rp`. `ap` and +// `rp` must both be `num` words long. It returns the carry word of the +// operation. `ap` and `rp` may be equal but otherwise may not alias. #if defined(BN_MUL_ASM) extern "C" #endif BN_ULONG bn_mul_words(BN_ULONG *rp, const BN_ULONG *ap, size_t num, BN_ULONG w); -// bn_sqr_add_words computes |tmp| where |tmp[2*i]| and |tmp[2*i+1]| are -// |ap[i]|'s square, for all |i| up to |num|, and adds the result to |rp|. If -// the result does not fit in |2*num| words, the final carry bit is truncated. -// |ap| is an array of |num| words and |rp| an array of |2*num| words. |ap| and -// |rp| may not alias. +// bn_sqr_add_words computes `tmp` where `tmp[2*i]` and `tmp[2*i+1]` are +// `ap[i]`'s square, for all `i` up to `num`, and adds the result to `rp`. If +// the result does not fit in `2*num` words, the final carry bit is truncated. +// `ap` is an array of `num` words and `rp` an array of `2*num` words. `ap` and +// `rp` may not alias. // -// This gives the contribution of the |ap[i]*ap[i]| terms when squaring |ap|. +// This gives the contribution of the `ap[i]*ap[i]` terms when squaring `ap`. #if defined(BN_MUL_ASM) extern "C" #endif void bn_sqr_add_words(BN_ULONG *rp, const BN_ULONG *ap, size_t num); -// bn_add_words adds |ap| to |bp| and places the result in |rp|, each of which -// are |num| words long. It returns the carry bit, which is one if the operation -// overflowed and zero otherwise. Any pair of |ap|, |bp|, and |rp| may be equal +// bn_add_words adds `ap` to `bp` and places the result in `rp`, each of which +// are `num` words long. It returns the carry bit, which is one if the operation +// overflowed and zero otherwise. Any pair of `ap`, `bp`, and `rp` may be equal // to each other but otherwise may not alias. #if defined(BN_ADD_ASM) @@ -228,9 +228,9 @@ BN_ULONG bn_add_words(BN_ULONG *rp, const BN_ULONG *ap, const BN_ULONG *bp, size_t num); -// bn_sub_words subtracts |bp| from |ap| and places the result in |rp|. It +// bn_sub_words subtracts `bp` from `ap` and places the result in `rp`. It // returns the borrow bit, which is one if the computation underflowed and zero -// otherwise. Any pair of |ap|, |bp|, and |rp| may be equal to each other but +// otherwise. Any pair of `ap`, `bp`, and `rp` may be equal to each other but // otherwise may not alias. #if defined(BN_ADD_ASM) extern "C" @@ -238,76 +238,76 @@ BN_ULONG bn_sub_words(BN_ULONG *rp, const BN_ULONG *ap, const BN_ULONG *bp, size_t num); -// bn_mul_comba4 sets |r| to the product of |a| and |b|. +// bn_mul_comba4 sets `r` to the product of `a` and `b`. #if defined(BN_MUL_ASM) extern "C" #endif void bn_mul_comba4(BN_ULONG r[8], const BN_ULONG a[4], const BN_ULONG b[4]); -// bn_mul_comba8 sets |r| to the product of |a| and |b|. +// bn_mul_comba8 sets `r` to the product of `a` and `b`. #if defined(BN_MUL_ASM) extern "C" #endif void bn_mul_comba8(BN_ULONG r[16], const BN_ULONG a[8], const BN_ULONG b[8]); -// bn_sqr_comba8 sets |r| to |a|^2. +// bn_sqr_comba8 sets `r` to `a`^2. #if defined(BN_MUL_ASM) extern "C" #endif void bn_sqr_comba8(BN_ULONG r[16], const BN_ULONG a[8]); -// bn_sqr_comba4 sets |r| to |a|^2. +// bn_sqr_comba4 sets `r` to `a`^2. #if defined(BN_MUL_ASM) extern "C" #endif void bn_sqr_comba4(BN_ULONG r[8], const BN_ULONG a[4]); -// bn_less_than_words returns one if |a| < |b| and zero otherwise, where |a| -// and |b| both are |len| words long. It runs in constant time. +// bn_less_than_words returns one if `a` < `b` and zero otherwise, where `a` +// and `b` both are `len` words long. It runs in constant time. int bn_less_than_words(const BN_ULONG *a, const BN_ULONG *b, size_t len); -// bn_in_range_words returns one if |min_inclusive| <= |a| < |max_exclusive|, -// where |a| and |max_exclusive| both are |len| words long. |a| and -// |max_exclusive| are treated as secret. +// bn_in_range_words returns one if `min_inclusive` <= `a` < `max_exclusive`, +// where `a` and `max_exclusive` both are `len` words long. `a` and +// `max_exclusive` are treated as secret. int bn_in_range_words(const BN_ULONG *a, BN_ULONG min_inclusive, const BN_ULONG *max_exclusive, size_t len); -// bn_rand_range_words sets |out| to a uniformly distributed random number from -// |min_inclusive| to |max_exclusive|. Both |out| and |max_exclusive| are |len| +// bn_rand_range_words sets `out` to a uniformly distributed random number from +// `min_inclusive` to `max_exclusive`. Both `out` and `max_exclusive` are `len` // words long. // -// This function runs in time independent of the result, but |min_inclusive| and -// |max_exclusive| are public data. (Information about the range is unavoidably +// This function runs in time independent of the result, but `min_inclusive` and +// `max_exclusive` are public data. (Information about the range is unavoidably // leaked by how many iterations it took to select a number.) int bn_rand_range_words(BN_ULONG *out, BN_ULONG min_inclusive, const BN_ULONG *max_exclusive, size_t len, const uint8_t additional_data[32]); -// bn_range_secret_range behaves like |BN_rand_range_ex|, but treats -// |max_exclusive| as secret. Because of this constraint, the distribution of +// bn_range_secret_range behaves like `BN_rand_range_ex`, but treats +// `max_exclusive` as secret. Because of this constraint, the distribution of // values returned is more complex. // // Rather than repeatedly generating values until one is in range, which would // leak information, it generates one value. If the value is in range, it sets -// |*out_is_uniform| to one. Otherwise, it sets |*out_is_uniform| to zero, +// `*out_is_uniform` to one. Otherwise, it sets `*out_is_uniform` to zero, // fixing up the value to force it in range. // -// The subset of calls to |bn_rand_secret_range| which set |*out_is_uniform| to +// The subset of calls to `bn_rand_secret_range` which set `*out_is_uniform` to // one are uniformly distributed in the target range. Calls overall are not. // This function is intended for use in situations where the extra values are // still usable and where the number of iterations needed to reach the target // number of uniform outputs may be blinded for negligible probabilities of // timing leaks. // -// Although this function treats |max_exclusive| as secret, it treats the number -// of bits in |max_exclusive| as public. +// Although this function treats `max_exclusive` as secret, it treats the number +// of bits in `max_exclusive` as public. int bn_rand_secret_range(BIGNUM *r, int *out_is_uniform, BN_ULONG min_inclusive, const BIGNUM *max_exclusive); -// BN_MONTGOMERY_MAX_WORDS is the maximum number of words allowed in a |BIGNUM| +// BN_MONTGOMERY_MAX_WORDS is the maximum number of words allowed in a `BIGNUM` // used with Montgomery reduction. Ideally this limit would be applied to all -// |BIGNUM|s, in |bn_wexpand|, but the exactfloat library needs to create 8 MiB +// `BIGNUM`s, in `bn_wexpand`, but the exactfloat library needs to create 8 MiB // values for other operations. // // This limit is set so that one number fits within 2 KiB, giving room to @@ -318,10 +318,10 @@ BSSL_NAMESPACE_END struct bn_mont_ctx_st { - // RR is R^2, reduced modulo |N|. It is used to convert to Montgomery form. It - // is guaranteed to have the same width as |N|. + // RR is R^2, reduced modulo `N`. It is used to convert to Montgomery form. It + // is guaranteed to have the same width as `N`. BIGNUM RR; - // N is the modulus. It is always stored in minimal form, so |N.width| + // N is the modulus. It is always stored in minimal form, so `N.width` // determines R. BIGNUM N; BN_ULONG n0[BN_MONT_CTX_N0_LIMBS]; // least significant words of (R*Ri-1)/N @@ -333,23 +333,23 @@ (defined(OPENSSL_X86) || defined(OPENSSL_X86_64) || \ defined(OPENSSL_ARM) || defined(OPENSSL_AARCH64)) #define OPENSSL_BN_ASM_MONT -// bn_mul_mont_words writes |ap| * |bp| mod |np| to |rp|, each |num| words -// long. Inputs and outputs are in Montgomery form. |n0| is a pointer to the -// corresponding field in |BN_MONT_CTX|. +// bn_mul_mont_words writes `ap` * `bp` mod `np` to `rp`, each `num` words +// long. Inputs and outputs are in Montgomery form. `n0` is a pointer to the +// corresponding field in `BN_MONT_CTX`. // -// If at least one of |ap| or |bp| is fully reduced, |rp| will be fully reduced. +// If at least one of `ap` or `bp` is fully reduced, `rp` will be fully reduced. // If neither is fully-reduced, the output may not be either. // -// This function allocates up to 2 * |num| words (plus a constant allocation) on -// the stack, so |num| should be at most |BN_MONTGOMERY_MAX_WORDS|. -// Additionally, |num| must be at least 128 / |BN_BITS2|. +// This function allocates up to 2 * `num` words (plus a constant allocation) on +// the stack, so `num` should be at most `BN_MONTGOMERY_MAX_WORDS`. +// Additionally, `num` must be at least 128 / `BN_BITS2`. // // TODO(davidben): The x86_64 implementation expects a 32-bit input and masks // off upper bits. The aarch64 implementation expects a 64-bit input and does -// not. |size_t| is the safer option but not strictly correct for x86_64. But -// the |BN_MONTGOMERY_MAX_WORDS| bound makes this moot. +// not. `size_t` is the safer option but not strictly correct for x86_64. But +// the `BN_MONTGOMERY_MAX_WORDS` bound makes this moot. // -// See also discussion in |ToWord| in abi_test.h for notes on smaller-than-word +// See also discussion in `ToWord` in abi_test.h for notes on smaller-than-word // inputs. extern "C" void bn_mul_mont_words(BN_ULONG *rp, const BN_ULONG *ap, const BN_ULONG *bp, const BN_ULONG *np, @@ -405,8 +405,8 @@ #if !defined(OPENSSL_NO_ASM) && defined(OPENSSL_X86_64) #define OPENSSL_BN_ASM_MONT5 -// The following functions implement |bn_mul_mont_gather5|. See -// |bn_mul_mont_gather5| for details. +// The following functions implement `bn_mul_mont_gather5`. See +// `bn_mul_mont_gather5` for details. inline int bn_mul4x_mont_gather5_capable(int num) { return (num & 7) == 0; } extern "C" void bn_mul4x_mont_gather5(BN_ULONG *rp, const BN_ULONG *ap, const BN_ULONG *table, const BN_ULONG *np, @@ -427,20 +427,20 @@ BN_ULONG *rp, const BN_ULONG *ap, const BN_ULONG *table, const BN_ULONG *np, const BN_ULONG n0[BN_MONT_CTX_N0_LIMBS], int num, int power); -// bn_scatter5 stores |inp| to index |power| of |table|. |inp| and each entry of -// |table| are |num| words long. |power| must be less than 32 and is treated as -// public. |table| must be 32*|num| words long. |table| must be aligned to at +// bn_scatter5 stores `inp` to index `power` of `table`. `inp` and each entry of +// `table` are `num` words long. `power` must be less than 32 and is treated as +// public. `table` must be 32*`num` words long. `table` must be aligned to at // least 16 bytes. extern "C" void bn_scatter5(const BN_ULONG *inp, size_t num, BN_ULONG *table, size_t power); -// bn_gather5 loads index |power| of |table| and stores it in |out|. |out| and -// each entry of |table| are |num| words long. |power| must be less than 32 and -// is treated as secret. |table| must be aligned to at least 16 bytes. +// bn_gather5 loads index `power` of `table` and stores it in `out`. `out` and +// each entry of `table` are `num` words long. `power` must be less than 32 and +// is treated as secret. `table` must be aligned to at least 16 bytes. extern "C" void bn_gather5(BN_ULONG *out, size_t num, const BN_ULONG *table, size_t power); -// The following functions implement |bn_power5|. See |bn_power5| for details. +// The following functions implement `bn_power5`. See `bn_power5` for details. extern "C" void bn_power5_nohw(BN_ULONG *rp, const BN_ULONG *ap, const BN_ULONG *table, const BN_ULONG *np, const BN_ULONG n0[BN_MONT_CTX_N0_LIMBS], int num, @@ -461,10 +461,10 @@ uint64_t bn_mont_n0(const BIGNUM *n); -// bn_mont_ctx_set_RR_consttime initializes |mont->RR|. It returns one on -// success and zero on error. |mont->N| and |mont->n0| must have been -// initialized already. The bit width of |mont->N| is assumed public, but -// |mont->N| is otherwise treated as secret. +// bn_mont_ctx_set_RR_consttime initializes `mont->RR`. It returns one on +// success and zero on error. `mont->N` and `mont->n0` must have been +// initialized already. The bit width of `mont->N` is assumed public, but +// `mont->N` is otherwise treated as secret. int bn_mont_ctx_set_RR_consttime(BN_MONT_CTX *mont, BN_CTX *ctx); #if defined(_MSC_VER) @@ -485,34 +485,34 @@ #error "Either BN_ULLONG or BN_UMULT_LOHI must be defined on every platform." #endif -// bn_jacobi returns the Jacobi symbol of |a| and |b| (which is -1, 0 or 1), or +// bn_jacobi returns the Jacobi symbol of `a` and `b` (which is -1, 0 or 1), or // -2 on error. int bn_jacobi(const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); -// bn_is_bit_set_words returns one if bit |bit| is set in |a| and zero +// bn_is_bit_set_words returns one if bit `bit` is set in `a` and zero // otherwise. int bn_is_bit_set_words(const BN_ULONG *a, size_t num, size_t bit); -// bn_one_to_montgomery sets |r| to one in Montgomery form. It returns one on +// bn_one_to_montgomery sets `r` to one in Montgomery form. It returns one on // success and zero on error. This function treats the bit width of the modulus // as public. int bn_one_to_montgomery(BIGNUM *r, const BN_MONT_CTX *mont, BN_CTX *ctx); -// bn_less_than_montgomery_R returns one if |bn| is less than the Montgomery R -// value for |mont| and zero otherwise. +// bn_less_than_montgomery_R returns one if `bn` is less than the Montgomery R +// value for `mont` and zero otherwise. int bn_less_than_montgomery_R(const BIGNUM *bn, const BN_MONT_CTX *mont); -// bn_mod_u16_consttime returns |bn| mod |d|, ignoring |bn|'s sign bit. It runs -// in time independent of the value of |bn|, but it treats |d| as public. +// bn_mod_u16_consttime returns `bn` mod `d`, ignoring `bn`'s sign bit. It runs +// in time independent of the value of `bn`, but it treats `d` as public. OPENSSL_EXPORT uint16_t bn_mod_u16_consttime(const BIGNUM *bn, uint16_t d); -// bn_odd_number_is_obviously_composite returns one if |bn| is divisible by one +// bn_odd_number_is_obviously_composite returns one if `bn` is divisible by one // of the first several odd primes and zero otherwise. int bn_odd_number_is_obviously_composite(const BIGNUM *bn); // A BN_MILLER_RABIN stores state common to each Miller-Rabin iteration. It is -// initialized within an existing |BN_CTX| scope and may not be used after -// that scope is released with |BN_CTX_end|. Field names match those in FIPS +// initialized within an existing `BN_CTX` scope and may not be used after +// that scope is released with `BN_CTX_end`. Field names match those in FIPS // 186-5, section B.3.1. typedef struct { // w1 is w-1. @@ -529,46 +529,46 @@ int a; } BN_MILLER_RABIN; -// bn_miller_rabin_init initializes |miller_rabin| for testing if |mont->N| is +// bn_miller_rabin_init initializes `miller_rabin` for testing if `mont->N` is // prime. It returns one on success and zero on error. OPENSSL_EXPORT int bn_miller_rabin_init(BN_MILLER_RABIN *miller_rabin, const BN_MONT_CTX *mont, BN_CTX *ctx); // bn_miller_rabin_iteration performs one Miller-Rabin iteration, checking if -// |b| is a composite witness for |mont->N|. |miller_rabin| must have been -// initialized with |bn_miller_rabin_setup|. On success, it returns one and sets -// |*out_is_possibly_prime| to one if |mont->N| may still be prime or zero if -// |b| shows it is composite. On allocation or internal failure, it returns +// `b` is a composite witness for `mont->N`. `miller_rabin` must have been +// initialized with `bn_miller_rabin_setup`. On success, it returns one and sets +// `*out_is_possibly_prime` to one if `mont->N` may still be prime or zero if +// `b` shows it is composite. On allocation or internal failure, it returns // zero. OPENSSL_EXPORT int bn_miller_rabin_iteration( const BN_MILLER_RABIN *miller_rabin, int *out_is_possibly_prime, const BIGNUM *b, const BN_MONT_CTX *mont, BN_CTX *ctx); -// bn_rshift1_words sets |r| to |a| >> 1, where both arrays are |num| bits wide. +// bn_rshift1_words sets `r` to `a` >> 1, where both arrays are `num` bits wide. void bn_rshift1_words(BN_ULONG *r, const BN_ULONG *a, size_t num); -// bn_rshift_words sets |r| to |a| >> |shift|, where both arrays are |num| bits +// bn_rshift_words sets `r` to `a` >> `shift`, where both arrays are `num` bits // wide. void bn_rshift_words(BN_ULONG *r, const BN_ULONG *a, unsigned shift, size_t num); -// bn_rshift_secret_shift behaves like |BN_rshift| but runs in time independent -// of both |a| and |n|. +// bn_rshift_secret_shift behaves like `BN_rshift` but runs in time independent +// of both `a` and `n`. OPENSSL_EXPORT int bn_rshift_secret_shift(BIGNUM *r, const BIGNUM *a, unsigned n, BN_CTX *ctx); -// bn_reduce_once sets |r| to |a| mod |m| where 0 <= |a| < 2*|m|. It returns -// zero if |a| < |m| and a mask of all ones if |a| >= |m|. Each array is |num| -// words long, but |a| has an additional word specified by |carry|. |carry| must -// be zero or one, as implied by the bounds on |a|. +// bn_reduce_once sets `r` to `a` mod `m` where 0 <= `a` < 2*`m`. It returns +// zero if `a` < `m` and a mask of all ones if `a` >= `m`. Each array is `num` +// words long, but `a` has an additional word specified by `carry`. `carry` must +// be zero or one, as implied by the bounds on `a`. // -// |r|, |a|, and |m| may not alias. Use |bn_reduce_once_in_place| if |r| and |a| +// `r`, `a`, and `m` may not alias. Use `bn_reduce_once_in_place` if `r` and `a` // must alias. BN_ULONG bn_reduce_once(BN_ULONG *r, const BN_ULONG *a, BN_ULONG carry, const BN_ULONG *m, size_t num); -// bn_reduce_once_in_place behaves like |bn_reduce_once| but acts in-place on -// |r|, using |tmp| as scratch space. |r|, |tmp|, and |m| may not alias. +// bn_reduce_once_in_place behaves like `bn_reduce_once` but acts in-place on +// `r`, using `tmp` as scratch space. `r`, `tmp`, and `m` may not alias. BN_ULONG bn_reduce_once_in_place(BN_ULONG *r, BN_ULONG carry, const BN_ULONG *m, BN_ULONG *tmp, size_t num); @@ -576,64 +576,64 @@ // Constant-time non-modular arithmetic. // // The following functions implement non-modular arithmetic in constant-time -// and pessimally set |r->width| to the largest possible word size. +// and pessimally set `r->width` to the largest possible word size. // // Note this means that, e.g., repeatedly multiplying by one will cause widths // to increase without bound. The corresponding public API functions minimize // their outputs to avoid regressing calculator consumers. -// bn_uadd_consttime behaves like |BN_uadd|, but it pessimally sets -// |r->width| = |a->width| + |b->width| + 1. +// bn_uadd_consttime behaves like `BN_uadd`, but it pessimally sets +// `r->width` = `a->width` + `b->width` + 1. int bn_uadd_consttime(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); -// bn_usub_consttime behaves like |BN_usub|, but it pessimally sets -// |r->width| = |a->width|. +// bn_usub_consttime behaves like `BN_usub`, but it pessimally sets +// `r->width` = `a->width`. int bn_usub_consttime(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); -// bn_abs_sub_consttime sets |r| to the absolute value of |a| - |b|, treating +// bn_abs_sub_consttime sets `r` to the absolute value of `a` - `b`, treating // both inputs as secret. It returns one on success and zero on error. OPENSSL_EXPORT int bn_abs_sub_consttime(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); -// bn_mul_consttime behaves like |BN_mul|, but it rejects negative inputs and -// pessimally sets |r->width| to |a->width| + |b->width|, to avoid leaking -// information about |a| and |b|. +// bn_mul_consttime behaves like `BN_mul`, but it rejects negative inputs and +// pessimally sets `r->width` to `a->width` + `b->width`, to avoid leaking +// information about `a` and `b`. int bn_mul_consttime(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); -// bn_sqrt_consttime behaves like |BN_sqrt|, but it pessimally sets |r->width| -// to 2*|a->width|, to avoid leaking information about |a| and |b|. +// bn_sqrt_consttime behaves like `BN_sqrt`, but it pessimally sets `r->width` +// to 2*`a->width`, to avoid leaking information about `a` and `b`. int bn_sqr_consttime(BIGNUM *r, const BIGNUM *a, BN_CTX *ctx); -// bn_div_consttime behaves like |BN_div|, but it rejects negative inputs and +// bn_div_consttime behaves like `BN_div`, but it rejects negative inputs and // treats both inputs, including their magnitudes, as secret. It is, as a -// result, much slower than |BN_div| and should only be used for rare operations -// where Montgomery reduction is not available. |divisor_min_bits| is a -// public lower bound for |BN_num_bits(divisor)|. When |divisor|'s bit width is +// result, much slower than `BN_div` and should only be used for rare operations +// where Montgomery reduction is not available. `divisor_min_bits` is a +// public lower bound for `BN_num_bits(divisor)`. When `divisor`'s bit width is // public, this can speed up the operation. // -// Note that |quotient->width| will be set pessimally to |numerator->width|. +// Note that `quotient->width` will be set pessimally to `numerator->width`. OPENSSL_EXPORT int bn_div_consttime(BIGNUM *quotient, BIGNUM *remainder, const BIGNUM *numerator, const BIGNUM *divisor, unsigned divisor_min_bits, BN_CTX *ctx); -// bn_is_relatively_prime checks whether GCD(|x|, |y|) is one. On success, it -// returns one and sets |*out_relatively_prime| to one if the GCD was one and +// bn_is_relatively_prime checks whether GCD(`x`, `y`) is one. On success, it +// returns one and sets `*out_relatively_prime` to one if the GCD was one and // zero otherwise. On error, it returns zero. OPENSSL_EXPORT int bn_is_relatively_prime(int *out_relatively_prime, const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); -// bn_lcm_consttime sets |r| to LCM(|a|, |b|). It returns one and success and -// zero on error. |a| and |b| are both treated as secret. +// bn_lcm_consttime sets `r` to LCM(`a`, `b`). It returns one and success and +// zero on error. `a` and `b` are both treated as secret. OPENSSL_EXPORT int bn_lcm_consttime(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); -// bn_mont_ctx_init zero-initialies |mont|. +// bn_mont_ctx_init zero-initialies `mont`. void bn_mont_ctx_init(BN_MONT_CTX *mont); -// bn_mont_ctx_cleanup releases memory associated with |mont|, without freeing -// |mont| itself. +// bn_mont_ctx_cleanup releases memory associated with `mont`, without freeing +// `mont` itself. void bn_mont_ctx_cleanup(BN_MONT_CTX *mont); @@ -641,65 +641,65 @@ // // The following functions implement basic constant-time modular arithmetic. -// bn_mod_add_words sets |r| to |a| + |b| (mod |m|), using |tmp| as scratch -// space. Each array is |num| words long. |a| and |b| must be < |m|. Any pair of -// |r|, |a|, and |b| may alias. +// bn_mod_add_words sets `r` to `a` + `b` (mod `m`), using `tmp` as scratch +// space. Each array is `num` words long. `a` and `b` must be < `m`. Any pair of +// `r`, `a`, and `b` may alias. void bn_mod_add_words(BN_ULONG *r, const BN_ULONG *a, const BN_ULONG *b, const BN_ULONG *m, BN_ULONG *tmp, size_t num); -// bn_mod_add_consttime acts like |BN_mod_add_quick| but takes a |BN_CTX|. +// bn_mod_add_consttime acts like `BN_mod_add_quick` but takes a `BN_CTX`. int bn_mod_add_consttime(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); -// bn_mod_sub_words sets |r| to |a| - |b| (mod |m|), using |tmp| as scratch -// space. Each array is |num| words long. |a| and |b| must be < |m|. Any pair of -// |r|, |a|, and |b| may alias. +// bn_mod_sub_words sets `r` to `a` - `b` (mod `m`), using `tmp` as scratch +// space. Each array is `num` words long. `a` and `b` must be < `m`. Any pair of +// `r`, `a`, and `b` may alias. void bn_mod_sub_words(BN_ULONG *r, const BN_ULONG *a, const BN_ULONG *b, const BN_ULONG *m, BN_ULONG *tmp, size_t num); -// bn_mod_sub_consttime acts like |BN_mod_sub_quick| but takes a |BN_CTX|. +// bn_mod_sub_consttime acts like `BN_mod_sub_quick` but takes a `BN_CTX`. int bn_mod_sub_consttime(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); -// bn_mod_lshift1_consttime acts like |BN_mod_lshift1_quick| but takes a -// |BN_CTX|. +// bn_mod_lshift1_consttime acts like `BN_mod_lshift1_quick` but takes a +// `BN_CTX`. int bn_mod_lshift1_consttime(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); -// bn_mod_lshift_consttime acts like |BN_mod_lshift_quick| but takes a |BN_CTX|. +// bn_mod_lshift_consttime acts like `BN_mod_lshift_quick` but takes a `BN_CTX`. int bn_mod_lshift_consttime(BIGNUM *r, const BIGNUM *a, int n, const BIGNUM *m, BN_CTX *ctx); -// bn_mod_inverse_consttime sets |r| to |a|^-1, mod |n|. |a| must be non- -// negative and less than |n|. It returns one on success and zero on error. On -// failure, if the failure was caused by |a| having no inverse mod |n| then -// |*out_no_inverse| will be set to one; otherwise it will be set to zero. +// bn_mod_inverse_consttime sets `r` to `a`^-1, mod `n`. `a` must be non- +// negative and less than `n`. It returns one on success and zero on error. On +// failure, if the failure was caused by `a` having no inverse mod `n` then +// `*out_no_inverse` will be set to one; otherwise it will be set to zero. // -// This function treats both |a| and |n| as secret, provided they are both non- +// This function treats both `a` and `n` as secret, provided they are both non- // zero and the inverse exists. It should only be used for even moduli where // none of the less general implementations are applicable. OPENSSL_EXPORT int bn_mod_inverse_consttime(BIGNUM *r, int *out_no_inverse, const BIGNUM *a, const BIGNUM *n, BN_CTX *ctx); -// bn_mod_inverse_prime sets |out| to the modular inverse of |a| modulo |p|, +// bn_mod_inverse_prime sets `out` to the modular inverse of `a` modulo `p`, // computed with Fermat's Little Theorem. It returns one on success and zero on -// error. If |mont_p| is NULL, one will be computed temporarily. +// error. If `mont_p` is NULL, one will be computed temporarily. int bn_mod_inverse_prime(BIGNUM *out, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx, const BN_MONT_CTX *mont_p); -// bn_mod_inverse_secret_prime behaves like |bn_mod_inverse_prime| but uses -// |BN_mod_exp_mont_consttime| instead of |BN_mod_exp_mont| in hopes of +// bn_mod_inverse_secret_prime behaves like `bn_mod_inverse_prime` but uses +// `BN_mod_exp_mont_consttime` instead of `BN_mod_exp_mont` in hopes of // protecting the exponent. int bn_mod_inverse_secret_prime(BIGNUM *out, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx, const BN_MONT_CTX *mont_p); -// BN_MONT_CTX_set_locked takes |lock| and checks whether |*pmont| is NULL. If -// so, it creates a new |BN_MONT_CTX| and sets the modulus for it to |mod|. It -// then stores it as |*pmont|. It returns one on success and zero on error. Note -// this function assumes |mod| is public. +// BN_MONT_CTX_set_locked takes `lock` and checks whether `*pmont` is NULL. If +// so, it creates a new `BN_MONT_CTX` and sets the modulus for it to `mod`. It +// then stores it as `*pmont`. It returns one on success and zero on error. Note +// this function assumes `mod` is public. // -// If |*pmont| is already non-NULL then it does nothing and returns one. +// If `*pmont` is already non-NULL then it does nothing and returns one. int BN_MONT_CTX_set_locked(UniquePtr<BN_MONT_CTX> *pmont, Mutex *lock, const BIGNUM *mod, BN_CTX *bn_ctx); @@ -720,80 +720,80 @@ #define BN_SMALL_MAX_WORDS 9 #endif -// bn_mul_small sets |r| to |a|*|b|. |num_r| must be |num_a| + |num_b|. |r| may -// not alias with |a| or |b|. +// bn_mul_small sets `r` to `a`*`b`. `num_r` must be `num_a` + `num_b`. `r` may +// not alias with `a` or `b`. void bn_mul_small(BN_ULONG *r, size_t num_r, const BN_ULONG *a, size_t num_a, const BN_ULONG *b, size_t num_b); -// bn_sqr_small sets |r| to |a|^2. |num_r| must be |num_a|*2. |r| and |a| may +// bn_sqr_small sets `r` to `a`^2. `num_r` must be `num_a`*2. `r` and `a` may // not alias. void bn_sqr_small(BN_ULONG *r, size_t num_r, const BN_ULONG *a, size_t num_a); -// In the following functions, the modulus must be at most |BN_SMALL_MAX_WORDS| +// In the following functions, the modulus must be at most `BN_SMALL_MAX_WORDS` // words long. -// bn_to_montgomery_small sets |r| to |a| translated to the Montgomery domain. -// |r| and |a| are |num| words long, which must be |mont->N.width|. |a| must be -// fully reduced and may alias |r|. +// bn_to_montgomery_small sets `r` to `a` translated to the Montgomery domain. +// `r` and `a` are `num` words long, which must be `mont->N.width`. `a` must be +// fully reduced and may alias `r`. void bn_to_montgomery_small(BN_ULONG *r, const BN_ULONG *a, size_t num, const BN_MONT_CTX *mont); -// bn_from_montgomery_small sets |r| to |a| translated out of the Montgomery -// domain. |r| and |a| are |num_r| and |num_a| words long, respectively. |num_r| -// must be |mont->N.width|. |a| must be at most |mont->N|^2 and may alias |r|. +// bn_from_montgomery_small sets `r` to `a` translated out of the Montgomery +// domain. `r` and `a` are `num_r` and `num_a` words long, respectively. `num_r` +// must be `mont->N.width`. `a` must be at most `mont->N`^2 and may alias `r`. // -// Unlike most of these functions, only |num_r| is bounded by -// |BN_SMALL_MAX_WORDS|. |num_a| may exceed it, but must be at most 2 * |num_r|. +// Unlike most of these functions, only `num_r` is bounded by +// `BN_SMALL_MAX_WORDS`. `num_a` may exceed it, but must be at most 2 * `num_r`. void bn_from_montgomery_small(BN_ULONG *r, size_t num_r, const BN_ULONG *a, size_t num_a, const BN_MONT_CTX *mont); -// bn_mod_mul_montgomery_small sets |r| to |a| * |b| mod |mont->N|. Both inputs -// and outputs are in the Montgomery domain. Each array is |num| words long, -// which must be |mont->N.width|. Any two of |r|, |a|, and |b| may alias. |a| -// and |b| must be reduced on input. +// bn_mod_mul_montgomery_small sets `r` to `a` * `b` mod `mont->N`. Both inputs +// and outputs are in the Montgomery domain. Each array is `num` words long, +// which must be `mont->N.width`. Any two of `r`, `a`, and `b` may alias. `a` +// and `b` must be reduced on input. void bn_mod_mul_montgomery_small(BN_ULONG *r, const BN_ULONG *a, const BN_ULONG *b, size_t num, const BN_MONT_CTX *mont); -// bn_mod_exp_mont_small sets |r| to |a|^|p| mod |mont->N|. It returns one on +// bn_mod_exp_mont_small sets `r` to `a`^`p` mod `mont->N`. It returns one on // success and zero on programmer or internal error. Both inputs and outputs are -// in the Montgomery domain. |r| and |a| are |num| words long, which must be -// |mont->N.width| and at most |BN_SMALL_MAX_WORDS|. |num_p|, measured in bits, -// must fit in |size_t|. |a| must be fully-reduced. This function runs in time -// independent of |a|, but |p| and |mont->N| are public values. |a| must be -// fully-reduced and may alias with |r|. +// in the Montgomery domain. `r` and `a` are `num` words long, which must be +// `mont->N.width` and at most `BN_SMALL_MAX_WORDS`. `num_p`, measured in bits, +// must fit in `size_t`. `a` must be fully-reduced. This function runs in time +// independent of `a`, but `p` and `mont->N` are public values. `a` must be +// fully-reduced and may alias with `r`. // -// Note this function differs from |BN_mod_exp_mont| which uses Montgomery +// Note this function differs from `BN_mod_exp_mont` which uses Montgomery // reduction but takes input and output outside the Montgomery domain. Combine -// this function with |bn_from_montgomery_small| and |bn_to_montgomery_small| +// this function with `bn_from_montgomery_small` and `bn_to_montgomery_small` // if necessary. void bn_mod_exp_mont_small(BN_ULONG *r, const BN_ULONG *a, size_t num, const BN_ULONG *p, size_t num_p, const BN_MONT_CTX *mont); -// bn_mod_inverse0_prime_mont_small sets |r| to |a|^-1 mod |mont->N|. If |a| is -// zero, |r| is set to zero. |mont->N| must be a prime. |r| and |a| are |num| -// words long, which must be |mont->N.width| and at most |BN_SMALL_MAX_WORDS|. -// |a| must be fully-reduced and may alias |r|. This function runs in time -// independent of |a|, but |mont->N| is a public value. +// bn_mod_inverse0_prime_mont_small sets `r` to `a`^-1 mod `mont->N`. If `a` is +// zero, `r` is set to zero. `mont->N` must be a prime. `r` and `a` are `num` +// words long, which must be `mont->N.width` and at most `BN_SMALL_MAX_WORDS`. +// `a` must be fully-reduced and may alias `r`. This function runs in time +// independent of `a`, but `mont->N` is a public value. void bn_mod_inverse0_prime_mont_small(BN_ULONG *r, const BN_ULONG *a, size_t num, const BN_MONT_CTX *mont); // Word-based byte conversion functions. -// bn_big_endian_to_words interprets |in_len| bytes from |in| as a big-endian, -// unsigned integer and writes the result to |out_len| words in |out|. |out_len| -// must be large enough to represent any |in_len|-byte value. That is, |in_len| -// must be at most |BN_BYTES * out_len|. +// bn_big_endian_to_words interprets `in_len` bytes from `in` as a big-endian, +// unsigned integer and writes the result to `out_len` words in `out`. `out_len` +// must be large enough to represent any `in_len`-byte value. That is, `in_len` +// must be at most `BN_BYTES * out_len`. void bn_big_endian_to_words(BN_ULONG *out, size_t out_len, const uint8_t *in, size_t in_len); -// bn_words_to_big_endian represents |in_len| words from |in| as a big-endian, -// unsigned integer in |out_len| bytes. It writes the result to |out|. |out_len| -// must be large enough to represent |in| without truncation. +// bn_words_to_big_endian represents `in_len` words from `in` as a big-endian, +// unsigned integer in `out_len` bytes. It writes the result to `out`. `out_len` +// must be large enough to represent `in` without truncation. // -// Note |out_len| may be less than |BN_BYTES * in_len| if |in| is known to have +// Note `out_len` may be less than `BN_BYTES * in_len` if `in` is known to have // leading zeros. void bn_words_to_big_endian(uint8_t *out, size_t out_len, const BN_ULONG *in, size_t in_len);
diff --git a/crypto/fipsmodule/bn/rsaz_exp.h b/crypto/fipsmodule/bn/rsaz_exp.h index 9bd3cb9..26df52a 100644 --- a/crypto/fipsmodule/bn/rsaz_exp.h +++ b/crypto/fipsmodule/bn/rsaz_exp.h
@@ -31,11 +31,11 @@ #if !defined(OPENSSL_NO_ASM) && defined(OPENSSL_X86_64) #define RSAZ_ENABLED -// RSAZ_1024_mod_exp_avx2 sets |result| to |base_norm| raised to |exponent| -// modulo |m_norm|. |base_norm| must be fully-reduced and |exponent| must have -// the high bit set (it is 1024 bits wide). |RR| and |k0| must be |RR| and |n0|, -// respectively, extracted from |m_norm|'s |BN_MONT_CTX|. |storage_words| is a -// temporary buffer that must be aligned to |MOD_EXP_CTIME_ALIGN| bytes. +// RSAZ_1024_mod_exp_avx2 sets `result` to `base_norm` raised to `exponent` +// modulo `m_norm`. `base_norm` must be fully-reduced and `exponent` must have +// the high bit set (it is 1024 bits wide). `RR` and `k0` must be `RR` and `n0`, +// respectively, extracted from `m_norm`'s `BN_MONT_CTX`. `storage_words` is a +// temporary buffer that must be aligned to `MOD_EXP_CTIME_ALIGN` bytes. void RSAZ_1024_mod_exp_avx2(BN_ULONG result[16], const BN_ULONG base_norm[16], const BN_ULONG exponent[16], const BN_ULONG m_norm[16], const BN_ULONG RR[16], @@ -62,43 +62,43 @@ // // See crypto/bn/asm/rsaz-avx2.pl for further details. -// rsaz_1024_norm2red_avx2 converts |norm| from |BIGNUM| to RSAZ representation -// and writes the result to |red|. +// rsaz_1024_norm2red_avx2 converts `norm` from `BIGNUM` to RSAZ representation +// and writes the result to `red`. extern "C" void rsaz_1024_norm2red_avx2(BN_ULONG red[40], const BN_ULONG norm[16]); -// rsaz_1024_mul_avx2 computes |a| * |b| mod |n| and writes the result to |ret|. -// Inputs and outputs are in Montgomery form, using RSAZ's representation. |k| -// is -|n|^-1 mod 2^64 or |n0| from |BN_MONT_CTX|. +// rsaz_1024_mul_avx2 computes `a` * `b` mod `n` and writes the result to `ret`. +// Inputs and outputs are in Montgomery form, using RSAZ's representation. `k` +// is -`n`^-1 mod 2^64 or `n0` from `BN_MONT_CTX`. extern "C" void rsaz_1024_mul_avx2(BN_ULONG ret[40], const BN_ULONG a[40], const BN_ULONG b[40], const BN_ULONG n[40], BN_ULONG k); -// rsaz_1024_mul_avx2 computes |a|^(2*|count|) mod |n| and writes the result to -// |ret|. Inputs and outputs are in Montgomery form, using RSAZ's -// representation. |k| is -|n|^-1 mod 2^64 or |n0| from |BN_MONT_CTX|. +// rsaz_1024_mul_avx2 computes `a`^(2*`count`) mod `n` and writes the result to +// `ret`. Inputs and outputs are in Montgomery form, using RSAZ's +// representation. `k` is -`n`^-1 mod 2^64 or `n0` from `BN_MONT_CTX`. extern "C" void rsaz_1024_sqr_avx2(BN_ULONG ret[40], const BN_ULONG a[40], const BN_ULONG n[40], BN_ULONG k, int count); -// rsaz_1024_scatter5_avx2 stores |val| at index |i| of |tbl|. |i| must be +// rsaz_1024_scatter5_avx2 stores `val` at index `i` of `tbl`. `i` must be // positive and at most 31. It is treated as public. Note the table only uses 18 -// |BN_ULONG|s per entry instead of 40. It packs two 29-bit limbs into each -// |BN_ULONG| and only stores 36 limbs rather than the padded 40. +// `BN_ULONG`s per entry instead of 40. It packs two 29-bit limbs into each +// `BN_ULONG` and only stores 36 limbs rather than the padded 40. extern "C" void rsaz_1024_scatter5_avx2(BN_ULONG tbl[32 * 18], const BN_ULONG val[40], int i); -// rsaz_1024_gather5_avx2 loads index |i| of |tbl| and writes it to |val|. |i| -// must be positive and at most 31. It is treated as secret. |tbl| must be +// rsaz_1024_gather5_avx2 loads index `i` of `tbl` and writes it to `val`. `i` +// must be positive and at most 31. It is treated as secret. `tbl` must be // aligned to 32 bytes. extern "C" void rsaz_1024_gather5_avx2(BN_ULONG val[40], const BN_ULONG tbl[32 * 18], int i); -// rsaz_1024_red2norm_avx2 converts |red| from RSAZ to |BIGNUM| representation -// and writes the result to |norm|. The result will be <= the modulus. +// rsaz_1024_red2norm_avx2 converts `red` from RSAZ to `BIGNUM` representation +// and writes the result to `norm`. The result will be <= the modulus. // -// WARNING: The result of this operation may not be fully reduced. |norm| may be +// WARNING: The result of this operation may not be fully reduced. `norm` may be // the modulus instead of zero. This function should be followed by a call to -// |bn_reduce_once|. +// `bn_reduce_once`. extern "C" void rsaz_1024_red2norm_avx2(BN_ULONG norm[16], const BN_ULONG red[40]);
diff --git a/crypto/fipsmodule/cipher/internal.h b/crypto/fipsmodule/cipher/internal.h index 0983b15..105ae43 100644 --- a/crypto/fipsmodule/cipher/internal.h +++ b/crypto/fipsmodule/cipher/internal.h
@@ -33,7 +33,7 @@ extern "C" { -// EVP_CIPH_MODE_MASK contains the bits of |flags| that represent the mode. +// EVP_CIPH_MODE_MASK contains the bits of `flags` that represent the mode. #define EVP_CIPH_MODE_MASK 0x3f // EVP_AEAD represents a specific AEAD algorithm. @@ -43,8 +43,8 @@ uint8_t overhead; uint8_t max_tag_len; - // init initialises an |EVP_AEAD_CTX|. If this call returns zero then - // |cleanup| will not be called for that context. + // init initialises an `EVP_AEAD_CTX`. If this call returns zero then + // `cleanup` will not be called for that context. int (*init)(EVP_AEAD_CTX *, const uint8_t *key, size_t key_len, size_t tag_len); int (*init_with_direction)(EVP_AEAD_CTX *, const uint8_t *key, size_t key_len, @@ -96,16 +96,16 @@ // cipher. unsigned ctx_size; - // flags contains the OR of a number of flags. See |EVP_CIPH_*|. + // flags contains the OR of a number of flags. See `EVP_CIPH_*`. uint32_t flags; int (*init)(EVP_CIPHER_CTX *ctx, const uint8_t *key, const uint8_t *iv, int enc); - // cipher encrypts/decrypts |in|, write output to |out|. Writes exactly |len| - // bytes, which must be a multiple of the |block_size|. + // cipher encrypts/decrypts `in`, write output to `out`. Writes exactly `len` + // bytes, which must be a multiple of the `block_size`. // - // For ciphers where encryption and decryption operations differ, |init| + // For ciphers where encryption and decryption operations differ, `init` // shall set an internal state for this. // // Returns 1 on success, or 0 on error. @@ -115,22 +115,22 @@ // cipher_final finalizes the cipher, performing possible final // authentication checks. // - // Only used for |EVP_CIPH_FLAG_CUSTOM_CIPHER| ciphers. + // Only used for `EVP_CIPH_FLAG_CUSTOM_CIPHER` ciphers. // // Returns 1 on success, or 0 on error. When decrypting, if an error is // returned, the decrypted data must not be used. int (*cipher_final)(EVP_CIPHER_CTX *ctx); - // update_aad adds |in| (of length |inl|) to the authenticated data for the + // update_aad adds `in` (of length `inl`) to the authenticated data for the // encryption operation. // - // Only used for |EVP_CIPH_FLAG_CUSTOM_CIPHER| ciphers. + // Only used for `EVP_CIPH_FLAG_CUSTOM_CIPHER` ciphers. // // Returns 1 on success, or 0 on error. int (*update_aad)(EVP_CIPHER_CTX *ctx, const uint8_t *in, size_t inl); // cleanup, if non-NULL, releases memory associated with the context. It is - // called if |EVP_CTRL_INIT| succeeds. Note that |init| may not have been + // called if `EVP_CTRL_INIT` succeeds. Note that `init` may not have been // called at this point. void (*cleanup)(EVP_CIPHER_CTX *); @@ -141,7 +141,7 @@ BSSL_NAMESPACE_BEGIN -// CopySpan copies an entire span of bytes from |from| to |to|. +// CopySpan copies an entire span of bytes from `from` to `to`. // // The spans need to have the same length. inline void CopySpan(Span<const uint8_t> from, Span<uint8_t> to) { @@ -149,7 +149,7 @@ std::copy(from.begin(), from.end(), to.begin()); } -// CopyToPrefix copies a span of bytes from |from| into |to|. It aborts +// CopyToPrefix copies a span of bytes from `from` into `to`. It aborts // if there is not enough space. // // TODO(crbug.com/404286922): Can we simplify this in a C++20 world (e.g. @@ -161,9 +161,9 @@ // Generic CRYPTO_IOVEC/CRYPTO_IVEC helpers. namespace iovec { -// IsValid returns whether the given |CRYPTO_IVEC| or |CRYPTO_IOVEC| is -// valid for use with public APIs, i.e. does not contain more than |SIZE_MAX| -// bytes and not more than |CRYPTO_IOVEC_MAX| chunks. Note that the `EVP_AEAD` +// IsValid returns whether the given `CRYPTO_IVEC` or `CRYPTO_IOVEC` is +// valid for use with public APIs, i.e. does not contain more than `SIZE_MAX` +// bytes and not more than `CRYPTO_IOVEC_MAX` chunks. Note that the `EVP_AEAD` // methods need to accept an arbitrary number of chunks. template <typename IVec> inline bool IsValid(Span<IVec> ivecs) { @@ -181,8 +181,8 @@ return true; } -// Length returns the total length in bytes of a given |CRYPTO_IVEC| or -// |CRYPTO_IOVEC|. +// Length returns the total length in bytes of a given `CRYPTO_IVEC` or +// `CRYPTO_IOVEC`. template <typename IVec> inline size_t TotalLength(Span<IVec> ivecs) { size_t total = 0; @@ -192,15 +192,15 @@ return total; } -// GetAndRemoveSuffix takes |suffix_buf.size()| final bytes from the given -// |CRYPTO_IVEC| or |CRYPTO_IOVEC| (mutating said iovec to no longer contain +// GetAndRemoveSuffix takes `suffix_buf.size()` final bytes from the given +// `CRYPTO_IVEC` or `CRYPTO_IOVEC` (mutating said iovec to no longer contain // those bytes) and returns them. // -// If the byte range is contained in a single chunk of |ivecs|, it will just -// return that span pointing into |ivecs|; otherwise, it will copy the bytes -// into |out| and return that. +// If the byte range is contained in a single chunk of `ivecs`, it will just +// return that span pointing into `ivecs`; otherwise, it will copy the bytes +// into `out` and return that. // -// If |ivecs| is too short, returns |nullopt|. +// If `ivecs` is too short, returns `nullopt`. template <typename IVec, typename ReadFromT = const uint8_t *, ReadFromT IVec::*ReadFrom = &IVec::in> inline std::optional<Span<const uint8_t>> GetAndRemoveSuffix( @@ -221,7 +221,7 @@ ivecs.back().len -= suffix_buf.size(); return Span(ivecs.back().*ReadFrom + ivecs.back().len, suffix_buf.size()); } - // Otherwise, collect it into the buffer while trimming |ivecs|. + // Otherwise, collect it into the buffer while trimming `ivecs`. Span<uint8_t> remaining = suffix_buf; while (!ivecs.empty()) { Span<const uint8_t> src(ivecs.back().*ReadFrom, ivecs.back().len); @@ -238,8 +238,8 @@ return std::nullopt; } -// GetAndRemoveOutSuffix is like |GetAndRemoveSuffix| but takes from a -// |CRYPTO_IOVEC|'s |out| member instead. +// GetAndRemoveOutSuffix is like `GetAndRemoveSuffix` but takes from a +// `CRYPTO_IOVEC`'s `out` member instead. inline std::optional<Span<const uint8_t>> GetAndRemoveOutSuffix( Span<uint8_t> out, Span<CRYPTO_IOVEC> iovecs) { return GetAndRemoveSuffix<CRYPTO_IOVEC, /*ReadFromT=*/uint8_t *, @@ -262,20 +262,20 @@ } } // namespace internal -// ForEachBlockRange iterates over the |ivecs| as follows: +// ForEachBlockRange iterates over the `ivecs` as follows: // -// - |f_whole| gets called on whole blocks crossing |ivecs| chunk boundaries, or +// - `f_whole` gets called on whole blocks crossing `ivecs` chunk boundaries, or // ranges of whole blocks that are entirely in chunks. -// - |f| gets called exactly once, on the last block range which may +// - `f` gets called exactly once, on the last block range which may // end up with a partial block. -// - Both functions receive an |in| pointer that either points into |ivecs| or -// into a chunk assembly buffer and a |len| which indicates the number of -// bytes from |in| that can be accessed. If the function returns 0, +// - Both functions receive an `in` pointer that either points into `ivecs` or +// into a chunk assembly buffer and a `len` which indicates the number of +// bytes from `in` that can be accessed. If the function returns 0, // iteration stops. -// - If |WriteOut| is set, |f_whole| and |f| receive an extra |out| +// - If `WriteOut` is set, `f_whole` and `f` receive an extra `out` // argument to which they can write output. This output will be placed into -// the |ivecs|'s |out| members either during or after the call. If iteration -// was stopped, the contents of |out| are indeterminate. +// the `ivecs`'s `out` members either during or after the call. If iteration +// was stopped, the contents of `out` are indeterminate. // - The return value is true if iteration was not stopped by the callbacks. template < size_t BlockSize, bool WriteOut = false, typename IVec, @@ -310,8 +310,8 @@ } }; - // Ensure the last item in |ivecs| is nonempty. This is necessary for - // detecting being at the end and calling |f_final| at the appropriate time. + // Ensure the last item in `ivecs` is nonempty. This is necessary for + // detecting being at the end and calling `f_final` at the appropriate time. Span<IVec> ivecs_trimmed = ivecs; while (!ivecs_trimmed.empty() && ivecs_trimmed.back().len == 0) { ivecs_trimmed = ivecs_trimmed.first(ivecs_trimmed.size() - 1); @@ -320,7 +320,7 @@ return call_func(f_final, IVec{}); } - // Now there are at least two non-empty |ivecs|, and neither the first nor the + // Now there are at least two non-empty `ivecs`, and neither the first nor the // last can be empty. MutableIVec current_range_head = ivecs_trimmed.front(); @@ -356,7 +356,7 @@ remove_prefix(collect_from_head, remaining); break; } - // Consume all of |ivec| and advance. + // Consume all of `ivec` and advance. in.Append(Span(collect_from_head.*ReadFrom, collect_from_head.len)); if (collect_from_rest.empty()) { // Nothing left - so this is the final block. @@ -378,12 +378,12 @@ } assert(in.size() == BlockSize); - // The above loop ensures this condition by the |break| only happening if - // |collect_from_head| has at least one byte remaining, and the loop + // The above loop ensures this condition by the `break` only happening if + // `collect_from_head` has at least one byte remaining, and the loop // otherwise ensuring as an invariant that the final chunk - which is - // nonempty - is among |collect_from_head| and |collect_from_rest|. + // nonempty - is among `collect_from_head` and `collect_from_rest`. // - // As such, at least one byte is remaining, and thus calling |f_whole| is + // As such, at least one byte is remaining, and thus calling `f_whole` is // appropriate. assert(collect_from_head.len != 0 || !collect_from_rest.empty()); @@ -406,15 +406,15 @@ } // If current_range_head.len is zero, then the last item of ivecs is empty. - // That however was excluded at the start of the function to ensure |f_final| + // That however was excluded at the start of the function to ensure `f_final` // is always used for the last call. assert(current_range_head.len != 0); return call_func(f_final, current_range_head); } -// ForEachOutBlockRange is like |ForEachBlockRange| but reads from a -// |CRYPTO_IOVEC|'s |out| member instead. +// ForEachOutBlockRange is like `ForEachBlockRange` but reads from a +// `CRYPTO_IOVEC`'s `out` member instead. template < size_t BlockSize, typename /* int(const uint8_t *in, [uint8_t *out,] size_t len) */ FWhole, @@ -428,7 +428,7 @@ f_final); } -// ForEachBlockRange_Dynamic is simply |ForEachBlockRange| with a +// ForEachBlockRange_Dynamic is simply `ForEachBlockRange` with a // runtime dispatch on the block size. template < bool WriteOut = false, typename IVec, typename ReadFromT = const uint8_t *,
diff --git a/crypto/fipsmodule/delocate.h b/crypto/fipsmodule/delocate.h index 7501548..b971085 100644 --- a/crypto/fipsmodule/delocate.h +++ b/crypto/fipsmodule/delocate.h
@@ -29,7 +29,7 @@ #if !defined(BORINGSSL_SHARED_LIBRARY) && defined(BORINGSSL_FIPS) && \ !defined(OPENSSL_ASAN) && !defined(OPENSSL_MSAN) #define DEFINE_BSS_GET(type, name, init_expr) \ - /* delocate needs C linkage and for |name| to be unique across BCM. */ \ + /* delocate needs C linkage and for `name` to be unique across BCM. */ \ extern "C" { \ extern type BCM_ADD_PREFIX(name); \ type BCM_ADD_PREFIX(name) init_expr; \ @@ -67,12 +67,12 @@ } \ static void name##_do_init(type *out) -// DEFINE_METHOD_FUNCTION defines a function named |name| which returns a -// method table of type const |type|*. In FIPS mode, to avoid rel.ro data, it +// DEFINE_METHOD_FUNCTION defines a function named `name` which returns a +// method table of type const `type`*. In FIPS mode, to avoid rel.ro data, it // is split into a CRYPTO_once_t-guarded initializer in the module and // unhashed, non-module accessor functions to space reserved in the BSS. The // method table is initialized by a caller-supplied function which takes a -// parameter named |out| of type |type|*. The caller should follow the macro +// parameter named `out` of type `type`*. The caller should follow the macro // invocation with the body of this function: // // DEFINE_METHOD_FUNCTION(EVP_MD, EVP_md4) {
diff --git a/crypto/fipsmodule/dh/internal.h b/crypto/fipsmodule/dh/internal.h index 337afa6..598154c 100644 --- a/crypto/fipsmodule/dh/internal.h +++ b/crypto/fipsmodule/dh/internal.h
@@ -36,7 +36,7 @@ UniquePtr<BIGNUM> priv_key; // x // priv_length contains the length, in bits, of the private value. If zero, - // the private value will be the same length as |p|. + // the private value will be the same length as `p`. unsigned priv_length = 0; mutable Mutex method_mont_p_lock; @@ -47,12 +47,12 @@ ~DHImpl() = default; }; -// dh_check_params_fast checks basic invariants on |dh|'s domain parameters. It -// does not check that |dh| forms a valid group, only that the sizes are within +// dh_check_params_fast checks basic invariants on `dh`'s domain parameters. It +// does not check that `dh` forms a valid group, only that the sizes are within // DoS bounds. int dh_check_params_fast(const DH *dh); -// dh_compute_key_padded_no_self_test does the same as |DH_compute_key_padded|, +// dh_compute_key_padded_no_self_test does the same as `DH_compute_key_padded`, // but doesn't try to run the self-test first. This is for use in the self tests // themselves, to prevent an infinite loop. int dh_compute_key_padded_no_self_test(unsigned char *out,
diff --git a/crypto/fipsmodule/digest/internal.h b/crypto/fipsmodule/digest/internal.h index 1174fcc..52090ce 100644 --- a/crypto/fipsmodule/digest/internal.h +++ b/crypto/fipsmodule/digest/internal.h
@@ -32,16 +32,16 @@ // md_size contains the size, in bytes, of the resulting digest. unsigned md_size; - // flags contains the OR of |EVP_MD_FLAG_*| values. + // flags contains the OR of `EVP_MD_FLAG_*` values. uint32_t flags; - // init initialises the state in |ctx->md_data|. + // init initialises the state in `ctx->md_data`. void (*init)(EVP_MD_CTX *ctx); - // update hashes |len| bytes of |data| into the state in |ctx->md_data|. + // update hashes `len` bytes of `data` into the state in `ctx->md_data`. void (*update)(EVP_MD_CTX *ctx, const void *data, size_t count); - // final completes the hash and writes |md_size| bytes of digest to |out|. + // final completes the hash and writes `md_size` bytes of digest to `out`. void (*final)(EVP_MD_CTX *ctx, uint8_t *out); // block_size contains the hash's native block size. @@ -51,15 +51,15 @@ unsigned ctx_size; }; -// evp_md_pctx_ops contains function pointers to allow the |pctx| member of -// |EVP_MD_CTX| to be manipulated without breaking layering by calling EVP +// evp_md_pctx_ops contains function pointers to allow the `pctx` member of +// `EVP_MD_CTX` to be manipulated without breaking layering by calling EVP // functions. struct evp_md_pctx_ops { - // free is called when an |EVP_MD_CTX| is being freed and the |pctx| also + // free is called when an `EVP_MD_CTX` is being freed and the `pctx` also // needs to be freed. void (*free)(EVP_PKEY_CTX *pctx); - // dup is called when an |EVP_MD_CTX| is copied and so the |pctx| also needs + // dup is called when an `EVP_MD_CTX` is copied and so the `pctx` also needs // to be copied. EVP_PKEY_CTX *(*dup)(EVP_PKEY_CTX *pctx); };
diff --git a/crypto/fipsmodule/digest/md32_common.h b/crypto/fipsmodule/digest/md32_common.h index 9e237b2..86f21dc 100644 --- a/crypto/fipsmodule/digest/md32_common.h +++ b/crypto/fipsmodule/digest/md32_common.h
@@ -44,9 +44,9 @@ // any truncation (e.g. 64 for SHA-224 and SHA-256, 128 for SHA-384 and // SHA-512). // -// |h| is the hash state and is updated by a function of type -// |crypto_md32_block_func|. |data| is the partial unprocessed block and has -// |num| bytes. |Nl| and |Nh| maintain the number of bits processed so far. +// `h` is the hash state and is updated by a function of type +// `crypto_md32_block_func`. `data` is the partial unprocessed block and has +// `num` bytes. `Nl` and `Nh` maintain the number of bits processed so far. // // The template parameter is then a traits struct defined as follows: // @@ -61,8 +61,8 @@ // // big or little endian. // static constexpr bool kLengthIsBigEndian = ...; // -// // HashBlocks incorporates |num_blocks| blocks of input from |data| -// // into |state|. It is assumed the caller has sized |state| and |data| +// // HashBlocks incorporates `num_blocks` blocks of input from `data` +// // into `state`. It is assumed the caller has sized `state` and `data` // // for the hash function. // static void HashBlocks(uint32_t *state, const uint8_t *data, // size_t num_blocks) { @@ -73,7 +73,7 @@ // The reason for this formulation is to encourage the compiler to specialize // all the code for the block size and block function. -// crypto_md32_update hashes |in| to |ctx|. +// crypto_md32_update hashes `in` to `ctx`. template <typename Traits> inline void crypto_md32_update(typename Traits::HashContext *ctx, Span<const uint8_t> in) { @@ -98,7 +98,7 @@ Traits::HashBlocks(ctx->h, ctx->data, 1); in = in.subspan(Traits::kBlockSize - n); ctx->num = 0; - // Keep |data| zeroed when unused. + // Keep `data` zeroed when unused. OPENSSL_memset(ctx->data, 0, Traits::kBlockSize); } else { OPENSSL_memcpy(ctx->data + n, in.data(), in.size()); @@ -120,19 +120,19 @@ } // crypto_md32_final incorporates the partial block and trailing length into the -// digest state in |ctx|. The trailing length is encoded in little-endian if -// |is_big_endian| is zero and big-endian otherwise. |data| must be a buffer of -// length |block_size| with the first |*num| bytes containing a partial block. -// |Nh| and |Nl| contain the total number of bits processed. On return, this -// function clears the partial block in |data| and -// |*num|. +// digest state in `ctx`. The trailing length is encoded in little-endian if +// `is_big_endian` is zero and big-endian otherwise. `data` must be a buffer of +// length `block_size` with the first `*num` bytes containing a partial block. +// `Nh` and `Nl` contain the total number of bits processed. On return, this +// function clears the partial block in `data` and +// `*num`. // -// This function does not serialize |h| into a final digest. This is the +// This function does not serialize `h` into a final digest. This is the // responsibility of the caller. template <typename Traits> inline void crypto_md32_final(typename Traits::HashContext *ctx) { static_assert(Traits::kBlockSize == sizeof(ctx->data), "block size is wrong"); - // |data| always has room for at least one byte. A full block would have + // `data` always has room for at least one byte. A full block would have // been consumed. size_t n = ctx->num; assert(n < Traits::kBlockSize);
diff --git a/crypto/fipsmodule/ec/internal.h b/crypto/fipsmodule/ec/internal.h index abcb77e..2261f20 100644 --- a/crypto/fipsmodule/ec/internal.h +++ b/crypto/fipsmodule/ec/internal.h
@@ -50,179 +50,179 @@ // Scalars. // An EC_SCALAR is an integer fully reduced modulo the order. Only the first -// |order->width| words are used. An |EC_SCALAR| is specific to an |EC_GROUP| +// `order->width` words are used. An `EC_SCALAR` is specific to an `EC_GROUP` // and must not be mixed between groups. typedef struct { BN_ULONG words[EC_MAX_WORDS]; } EC_SCALAR; -// ec_bignum_to_scalar converts |in| to an |EC_SCALAR| and writes it to -// |*out|. It returns one on success and zero if |in| is out of range. +// ec_bignum_to_scalar converts `in` to an `EC_SCALAR` and writes it to +// `*out`. It returns one on success and zero if `in` is out of range. int ec_bignum_to_scalar(const EC_GROUP *group, EC_SCALAR *out, const BIGNUM *in); -// ec_scalar_to_bytes serializes |in| as a big-endian bytestring to |out| and -// sets |*out_len| to the number of bytes written. The number of bytes written -// is |BN_num_bytes(&group->order)|, which is at most |EC_MAX_BYTES|. +// ec_scalar_to_bytes serializes `in` as a big-endian bytestring to `out` and +// sets `*out_len` to the number of bytes written. The number of bytes written +// is `BN_num_bytes(&group->order)`, which is at most `EC_MAX_BYTES`. void ec_scalar_to_bytes(const EC_GROUP *group, uint8_t *out, size_t *out_len, const EC_SCALAR *in); -// ec_scalar_from_bytes deserializes |in| and stores the resulting scalar over -// group |group| to |out|. It returns one on success and zero if |in| is +// ec_scalar_from_bytes deserializes `in` and stores the resulting scalar over +// group `group` to `out`. It returns one on success and zero if `in` is // invalid. int ec_scalar_from_bytes(const EC_GROUP *group, EC_SCALAR *out, const uint8_t *in, size_t len); -// ec_scalar_reduce sets |out| to |words|, reduced modulo the group order. -// |words| must be less than order^2. |num| must be at most twice the width of -// group order. This function treats |words| as secret. +// ec_scalar_reduce sets `out` to `words`, reduced modulo the group order. +// `words` must be less than order^2. `num` must be at most twice the width of +// group order. This function treats `words` as secret. void ec_scalar_reduce(const EC_GROUP *group, EC_SCALAR *out, const BN_ULONG *words, size_t num); -// ec_random_nonzero_scalar sets |out| to a uniformly selected random value from -// zero to |group->order| - 1. It returns one on success and zero on error. +// ec_random_nonzero_scalar sets `out` to a uniformly selected random value from +// zero to `group->order` - 1. It returns one on success and zero on error. int ec_random_scalar(const EC_GROUP *group, EC_SCALAR *out, const uint8_t additional_data[32]); -// ec_random_nonzero_scalar sets |out| to a uniformly selected random value from -// 1 to |group->order| - 1. It returns one on success and zero on error. +// ec_random_nonzero_scalar sets `out` to a uniformly selected random value from +// 1 to `group->order` - 1. It returns one on success and zero on error. int ec_random_nonzero_scalar(const EC_GROUP *group, EC_SCALAR *out, const uint8_t additional_data[32]); -// ec_scalar_equal_vartime returns one if |a| and |b| are equal and zero +// ec_scalar_equal_vartime returns one if `a` and `b` are equal and zero // otherwise. Both values are treated as public. int ec_scalar_equal_vartime(const EC_GROUP *group, const EC_SCALAR *a, const EC_SCALAR *b); -// ec_scalar_is_zero returns one if |a| is zero and zero otherwise. +// ec_scalar_is_zero returns one if `a` is zero and zero otherwise. int ec_scalar_is_zero(const EC_GROUP *group, const EC_SCALAR *a); -// ec_scalar_add sets |r| to |a| + |b|. +// ec_scalar_add sets `r` to `a` + `b`. void ec_scalar_add(const EC_GROUP *group, EC_SCALAR *r, const EC_SCALAR *a, const EC_SCALAR *b); -// ec_scalar_sub sets |r| to |a| - |b|. +// ec_scalar_sub sets `r` to `a` - `b`. void ec_scalar_sub(const EC_GROUP *group, EC_SCALAR *r, const EC_SCALAR *a, const EC_SCALAR *b); -// ec_scalar_neg sets |r| to -|a|. +// ec_scalar_neg sets `r` to -`a`. void ec_scalar_neg(const EC_GROUP *group, EC_SCALAR *r, const EC_SCALAR *a); -// ec_scalar_to_montgomery sets |r| to |a| in Montgomery form. +// ec_scalar_to_montgomery sets `r` to `a` in Montgomery form. void ec_scalar_to_montgomery(const EC_GROUP *group, EC_SCALAR *r, const EC_SCALAR *a); -// ec_scalar_to_montgomery sets |r| to |a| converted from Montgomery form. +// ec_scalar_to_montgomery sets `r` to `a` converted from Montgomery form. void ec_scalar_from_montgomery(const EC_GROUP *group, EC_SCALAR *r, const EC_SCALAR *a); -// ec_scalar_mul_montgomery sets |r| to |a| * |b| where inputs and outputs are +// ec_scalar_mul_montgomery sets `r` to `a` * `b` where inputs and outputs are // in Montgomery form. void ec_scalar_mul_montgomery(const EC_GROUP *group, EC_SCALAR *r, const EC_SCALAR *a, const EC_SCALAR *b); -// ec_scalar_inv0_montgomery sets |r| to |a|^-1 where inputs and outputs are in -// Montgomery form. If |a| is zero, |r| is set to zero. +// ec_scalar_inv0_montgomery sets `r` to `a`^-1 where inputs and outputs are in +// Montgomery form. If `a` is zero, `r` is set to zero. void ec_scalar_inv0_montgomery(const EC_GROUP *group, EC_SCALAR *r, const EC_SCALAR *a); -// ec_scalar_to_montgomery_inv_vartime sets |r| to |a|^-1 R. That is, it takes -// in |a| not in Montgomery form and computes the inverse in Montgomery form. It -// returns one on success and zero if |a| has no inverse. This function assumes -// |a| is public and may leak information about it via timing. +// ec_scalar_to_montgomery_inv_vartime sets `r` to `a`^-1 R. That is, it takes +// in `a` not in Montgomery form and computes the inverse in Montgomery form. It +// returns one on success and zero if `a` has no inverse. This function assumes +// `a` is public and may leak information about it via timing. // -// Note this is not the same operation as |ec_scalar_inv0_montgomery|. +// Note this is not the same operation as `ec_scalar_inv0_montgomery`. int ec_scalar_to_montgomery_inv_vartime(const EC_GROUP *group, EC_SCALAR *r, const EC_SCALAR *a); -// ec_scalar_select, in constant time, sets |out| to |a| if |mask| is all ones -// and |b| if |mask| is all zeros. +// ec_scalar_select, in constant time, sets `out` to `a` if `mask` is all ones +// and `b` if `mask` is all zeros. void ec_scalar_select(const EC_GROUP *group, EC_SCALAR *out, BN_ULONG mask, const EC_SCALAR *a, const EC_SCALAR *b); // Field elements. -// An EC_FELEM represents a field element. Only the first |field->width| words -// are used. An |EC_FELEM| is specific to an |EC_GROUP| and must not be mixed +// An EC_FELEM represents a field element. Only the first `field->width` words +// are used. An `EC_FELEM` is specific to an `EC_GROUP` and must not be mixed // between groups. Unless otherwise stated, all inputs and outputs are in // Montgomery form. typedef struct { BN_ULONG words[EC_MAX_WORDS]; } EC_FELEM; -// ec_felem_one returns one in |group|'s field. +// ec_felem_one returns one in `group`'s field. const EC_FELEM *ec_felem_one(const EC_GROUP *group); -// ec_bignum_to_felem converts |in| to an |EC_FELEM|. It returns one on success -// and zero if |in| is out of range. +// ec_bignum_to_felem converts `in` to an `EC_FELEM`. It returns one on success +// and zero if `in` is out of range. int ec_bignum_to_felem(const EC_GROUP *group, EC_FELEM *out, const BIGNUM *in); -// ec_felem_to_bignum converts |in| to a |BIGNUM|. It returns one on success and +// ec_felem_to_bignum converts `in` to a `BIGNUM`. It returns one on success and // zero on allocation failure. int ec_felem_to_bignum(const EC_GROUP *group, BIGNUM *out, const EC_FELEM *in); -// ec_felem_to_bytes serializes |in| as a big-endian bytestring to |out| and -// sets |*out_len| to the number of bytes written. The number of bytes written -// is |BN_num_bytes(&group->order)|, which is at most |EC_MAX_BYTES|. +// ec_felem_to_bytes serializes `in` as a big-endian bytestring to `out` and +// sets `*out_len` to the number of bytes written. The number of bytes written +// is `BN_num_bytes(&group->order)`, which is at most `EC_MAX_BYTES`. void ec_felem_to_bytes(const EC_GROUP *group, uint8_t *out, size_t *out_len, const EC_FELEM *in); -// ec_felem_from_bytes deserializes |in| and stores the resulting field element -// to |out|. It returns one on success and zero if |in| is invalid. +// ec_felem_from_bytes deserializes `in` and stores the resulting field element +// to `out`. It returns one on success and zero if `in` is invalid. int ec_felem_from_bytes(const EC_GROUP *group, EC_FELEM *out, const uint8_t *in, size_t len); -// ec_felem_neg sets |out| to -|a|. +// ec_felem_neg sets `out` to -`a`. void ec_felem_neg(const EC_GROUP *group, EC_FELEM *out, const EC_FELEM *a); -// ec_felem_add sets |out| to |a| + |b|. +// ec_felem_add sets `out` to `a` + `b`. void ec_felem_add(const EC_GROUP *group, EC_FELEM *out, const EC_FELEM *a, const EC_FELEM *b); -// ec_felem_add sets |out| to |a| - |b|. +// ec_felem_add sets `out` to `a` - `b`. void ec_felem_sub(const EC_GROUP *group, EC_FELEM *out, const EC_FELEM *a, const EC_FELEM *b); -// ec_felem_non_zero_mask returns all ones if |a| is non-zero and all zeros +// ec_felem_non_zero_mask returns all ones if `a` is non-zero and all zeros // otherwise. BN_ULONG ec_felem_non_zero_mask(const EC_GROUP *group, const EC_FELEM *a); -// ec_felem_select, in constant time, sets |out| to |a| if |mask| is all ones -// and |b| if |mask| is all zeros. +// ec_felem_select, in constant time, sets `out` to `a` if `mask` is all ones +// and `b` if `mask` is all zeros. void ec_felem_select(const EC_GROUP *group, EC_FELEM *out, BN_ULONG mask, const EC_FELEM *a, const EC_FELEM *b); -// ec_felem_equal returns one if |a| and |b| are equal and zero otherwise. +// ec_felem_equal returns one if `a` and `b` are equal and zero otherwise. int ec_felem_equal(const EC_GROUP *group, const EC_FELEM *a, const EC_FELEM *b); -// ec_felem_mul sets |out| to |a| * |b|. +// ec_felem_mul sets `out` to `a` * `b`. void ec_felem_mul(const EC_GROUP *group, EC_FELEM *out, const EC_FELEM *a, const EC_FELEM *b); -// ec_felem_sqr sets |out| to |a|^2. +// ec_felem_sqr sets `out` to `a`^2. void ec_felem_sqr(const EC_GROUP *group, EC_FELEM *out, const EC_FELEM *a); -// ec_felem_to_montgomery sets |out| to |a| converted to Montgomery form. +// ec_felem_to_montgomery sets `out` to `a` converted to Montgomery form. void ec_felem_to_montgomery(const EC_GROUP *group, EC_FELEM *out, const EC_FELEM *a); -// ec_felem_from_montgomery sets |out| to |a| converted from Montgomery form. +// ec_felem_from_montgomery sets `out` to `a` converted from Montgomery form. void ec_felem_from_montgomery(const EC_GROUP *group, EC_FELEM *out, const EC_FELEM *a); -// ec_felem_reduce sets |out| to |words|, reduced modulo the field size, p. -// |words| must be less than p^2. |num| must be at most twice the width of p. -// This function treats |words| as secret. +// ec_felem_reduce sets `out` to `words`, reduced modulo the field size, p. +// `words` must be less than p^2. `num` must be at most twice the width of p. +// This function treats `words` as secret. void ec_felem_reduce(const EC_GROUP *group, EC_FELEM *out, const BN_ULONG *words, size_t num); -// ec_felem_exp sets |out| to |a|^|exp|. It treats |a| is secret but |exp| as +// ec_felem_exp sets `out` to `a`^`exp`. It treats `a` is secret but `exp` as // public. // // TODO(crbug.com/42290435): hash-to-curve uses this as part of computing a // square root, which is what compressed coordinates ultimately needs to avoid -// |BIGNUM|. Can we unify this a bit? By generalizing to arbitrary +// `BIGNUM`. Can we unify this a bit? By generalizing to arbitrary // exponentiation, we also miss an opportunity to use a specialized addition // chain. We also miss our specialized field arithmetic for P-256. void ec_felem_exp(const EC_GROUP *group, EC_FELEM *out, const EC_FELEM *a, @@ -231,8 +231,8 @@ // Points. // -// Points may represented in affine coordinates as |EC_AFFINE| or Jacobian -// coordinates as |EC_JACOBIAN|. Affine coordinates directly represent a +// Points may represented in affine coordinates as `EC_AFFINE` or Jacobian +// coordinates as `EC_JACOBIAN`. Affine coordinates directly represent a // point on the curve, but point addition over affine coordinates requires // costly field inversions, so arithmetic is done in Jacobian coordinates. // Converting from affine to Jacobian is cheap, while converting from Jacobian @@ -240,8 +240,8 @@ // inversions needed in a sequence of point operations.) // An EC_JACOBIAN represents an elliptic curve point in Jacobian coordinates. -// Unlike |EC_POINT|, it is a plain struct which can be stack-allocated and -// needs no cleanup. It is specific to an |EC_GROUP| and must not be mixed +// Unlike `EC_POINT`, it is a plain struct which can be stack-allocated and +// needs no cleanup. It is specific to an `EC_GROUP` and must not be mixed // between groups. typedef struct { // X, Y, and Z are Jacobian projective coordinates. They represent @@ -256,23 +256,23 @@ EC_FELEM X, Y; } EC_AFFINE; -// ec_affine_to_jacobian converts |p| to Jacobian form and writes the result to -// |*out|. This operation is very cheap and only costs a few copies. +// ec_affine_to_jacobian converts `p` to Jacobian form and writes the result to +// `*out`. This operation is very cheap and only costs a few copies. void ec_affine_to_jacobian(const EC_GROUP *group, EC_JACOBIAN *out, const EC_AFFINE *p); -// ec_jacobian_to_affine converts |p| to affine form and writes the result to -// |*out|. It returns one on success and zero if |p| was the point at infinity. +// ec_jacobian_to_affine converts `p` to affine form and writes the result to +// `*out`. It returns one on success and zero if `p` was the point at infinity. // This operation performs a field inversion and should only be done once per // point. // -// If only extracting the x-coordinate, use |ec_get_x_coordinate_*| which is +// If only extracting the x-coordinate, use `ec_get_x_coordinate_*` which is // slightly faster. int ec_jacobian_to_affine(const EC_GROUP *group, EC_AFFINE *out, const EC_JACOBIAN *p); -// ec_jacobian_to_affine_batch converts |num| points in |in| from Jacobian -// coordinates to affine coordinates and writes the results to |out|. It returns +// ec_jacobian_to_affine_batch converts `num` points in `in` from Jacobian +// coordinates to affine coordinates and writes the results to `out`. It returns // one on success and zero if any of the input points were infinity. // // This function is not implemented for all curves. Add implementations as @@ -280,36 +280,36 @@ int ec_jacobian_to_affine_batch(const EC_GROUP *group, EC_AFFINE *out, const EC_JACOBIAN *in, size_t num); -// ec_point_set_affine_coordinates sets |out|'s to a point with affine -// coordinates |x| and |y|. It returns one if the point is on the curve and -// zero otherwise. If the point is not on the curve, the value of |out| is +// ec_point_set_affine_coordinates sets `out`'s to a point with affine +// coordinates `x` and `y`. It returns one if the point is on the curve and +// zero otherwise. If the point is not on the curve, the value of `out` is // undefined. int ec_point_set_affine_coordinates(const EC_GROUP *group, EC_AFFINE *out, const EC_FELEM *x, const EC_FELEM *y); -// ec_point_mul_no_self_test does the same as |EC_POINT_mul|, but doesn't try to +// ec_point_mul_no_self_test does the same as `EC_POINT_mul`, but doesn't try to // run the self-test first. This is for use in the self tests themselves, to // prevent an infinite loop. int 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); -// ec_point_mul_scalar sets |r| to |p| * |scalar|. Both inputs are considered +// ec_point_mul_scalar sets `r` to `p` * `scalar`. Both inputs are considered // secret. int ec_point_mul_scalar(const EC_GROUP *group, EC_JACOBIAN *r, const EC_JACOBIAN *p, const EC_SCALAR *scalar); -// ec_point_mul_scalar_base sets |r| to generator * |scalar|. |scalar| is +// ec_point_mul_scalar_base sets `r` to generator * `scalar`. `scalar` is // treated as secret. int ec_point_mul_scalar_base(const EC_GROUP *group, EC_JACOBIAN *r, const EC_SCALAR *scalar); -// ec_point_mul_scalar_batch sets |r| to |p0| * |scalar0| + |p1| * |scalar1| + -// |p2| * |scalar2|. |p2| may be NULL to skip that term. +// ec_point_mul_scalar_batch sets `r` to `p0` * `scalar0` + `p1` * `scalar1` + +// `p2` * `scalar2`. `p2` may be NULL to skip that term. // // The inputs are treated as secret, however, this function leaks information // about whether intermediate computations add a point to itself. Callers must -// ensure that discrete logs between |p0|, |p1|, and |p2| are uniformly +// ensure that discrete logs between `p0`, `p1`, and `p2` are uniformly // distributed and independent of the scalars, which should be uniformly // selected and not under the attackers control. This ensures the doubling case // will occur with negligible probability. @@ -318,7 +318,7 @@ // needed. // // TODO(davidben): This function does not use base point tables. For now, it is -// only used with the generic |EC_GFp_mont_method| implementation which has +// only used with the generic `EC_GFp_mont_method` implementation which has // none. If generalizing to tuned curves, this may be useful. However, we still // must double up to the least efficient input, so precomputed tables can only // save table setup and allow a wider window size. @@ -329,16 +329,16 @@ #define EC_MONT_PRECOMP_COMB_SIZE 5 -// An |EC_PRECOMP| stores precomputed information about a point, to optimize +// An `EC_PRECOMP` stores precomputed information about a point, to optimize // repeated multiplications involving it. It is a union so different -// |EC_METHOD|s can store different information in it. +// `EC_METHOD`s can store different information in it. typedef union { EC_AFFINE comb[(1 << EC_MONT_PRECOMP_COMB_SIZE) - 1]; } EC_PRECOMP; -// ec_init_precomp precomputes multiples of |p| and writes the result to |out|. +// ec_init_precomp precomputes multiples of `p` and writes the result to `out`. // It returns one on success and zero on error. The resulting table may be used -// with |ec_point_mul_scalar_precomp|. This function will fail if |p| is the +// with `ec_point_mul_scalar_precomp`. This function will fail if `p` is the // point at infinity. // // This function is not implemented for all curves. Add implementations as @@ -346,16 +346,16 @@ int ec_init_precomp(const EC_GROUP *group, EC_PRECOMP *out, const EC_JACOBIAN *p); -// ec_point_mul_scalar_precomp sets |r| to |p0| * |scalar0| + |p1| * |scalar1| + -// |p2| * |scalar2|. |p1| or |p2| may be NULL to skip the corresponding term. -// The points are represented as |EC_PRECOMP| and must be initialized with -// |ec_init_precomp|. This function runs faster than |ec_point_mul_scalar_batch| +// ec_point_mul_scalar_precomp sets `r` to `p0` * `scalar0` + `p1` * `scalar1` + +// `p2` * `scalar2`. `p1` or `p2` may be NULL to skip the corresponding term. +// The points are represented as `EC_PRECOMP` and must be initialized with +// `ec_init_precomp`. This function runs faster than `ec_point_mul_scalar_batch` // but requires setup work per input point, so it is only appropriate for points // which are used frequently. // // The inputs are treated as secret, however, this function leaks information // about whether intermediate computations add a point to itself. Callers must -// ensure that discrete logs between |p0|, |p1|, and |p2| are uniformly +// ensure that discrete logs between `p0`, `p1`, and `p2` are uniformly // distributed and independent of the scalars, which should be uniformly // selected and not under the attackers control. This ensures the doubling case // will occur with negligible probability. @@ -364,7 +364,7 @@ // needed. // // TODO(davidben): This function does not use base point tables. For now, it is -// only used with the generic |EC_GFp_mont_method| implementation which has +// only used with the generic `EC_GFp_mont_method` implementation which has // none. If generalizing to tuned curves, we should add a parameter for the base // point and arrange for the generic implementation to have base point tables // available. @@ -373,17 +373,17 @@ const EC_PRECOMP *p1, const EC_SCALAR *scalar1, const EC_PRECOMP *p2, const EC_SCALAR *scalar2); -// ec_point_mul_scalar_public sets |r| to -// generator * |g_scalar| + |p| * |p_scalar|. It assumes that the inputs are +// ec_point_mul_scalar_public sets `r` to +// generator * `g_scalar` + `p` * `p_scalar`. It assumes that the inputs are // public so there is no concern about leaking their values through timing. int ec_point_mul_scalar_public(const EC_GROUP *group, EC_JACOBIAN *r, const EC_SCALAR *g_scalar, const EC_JACOBIAN *p, const EC_SCALAR *p_scalar); -// ec_point_mul_scalar_public_batch sets |r| to the sum of generator * -// |g_scalar| and |points[i]| * |scalars[i]| where |points| and |scalars| have -// |num| elements. It assumes that the inputs are public so there is no concern -// about leaking their values through timing. |g_scalar| may be NULL to skip +// ec_point_mul_scalar_public_batch sets `r` to the sum of generator * +// `g_scalar` and `points[i]` * `scalars[i]` where `points` and `scalars` have +// `num` elements. It assumes that the inputs are public so there is no concern +// about leaking their values through timing. `g_scalar` may be NULL to skip // that term. // // This function is not implemented for all curves. Add implementations as @@ -393,33 +393,33 @@ const EC_JACOBIAN *points, const EC_SCALAR *scalars, size_t num); -// ec_point_select, in constant time, sets |out| to |a| if |mask| is all ones -// and |b| if |mask| is all zeros. +// ec_point_select, in constant time, sets `out` to `a` if `mask` is all ones +// and `b` if `mask` is all zeros. void ec_point_select(const EC_GROUP *group, EC_JACOBIAN *out, BN_ULONG mask, const EC_JACOBIAN *a, const EC_JACOBIAN *b); -// ec_affine_select behaves like |ec_point_select| but acts on affine points. +// ec_affine_select behaves like `ec_point_select` but acts on affine points. void ec_affine_select(const EC_GROUP *group, EC_AFFINE *out, BN_ULONG mask, const EC_AFFINE *a, const EC_AFFINE *b); -// ec_precomp_select behaves like |ec_point_select| but acts on |EC_PRECOMP|. +// ec_precomp_select behaves like `ec_point_select` but acts on `EC_PRECOMP`. void ec_precomp_select(const EC_GROUP *group, EC_PRECOMP *out, BN_ULONG mask, const EC_PRECOMP *a, const EC_PRECOMP *b); -// ec_cmp_x_coordinate compares the x (affine) coordinate of |p|, mod the group -// order, with |r|. It returns one if the values match and zero if |p| is the -// point at infinity of the values do not match. |p| is treated as public. +// ec_cmp_x_coordinate compares the x (affine) coordinate of `p`, mod the group +// order, with `r`. It returns one if the values match and zero if `p` is the +// point at infinity of the values do not match. `p` is treated as public. int ec_cmp_x_coordinate(const EC_GROUP *group, const EC_JACOBIAN *p, const EC_SCALAR *r); -// ec_get_x_coordinate_as_scalar sets |*out| to |p|'s x-coordinate, modulo -// |group->order|. It returns one on success and zero if |p| is the point at +// ec_get_x_coordinate_as_scalar sets `*out` to `p`'s x-coordinate, modulo +// `group->order`. It returns one on success and zero if `p` is the point at // infinity. int ec_get_x_coordinate_as_scalar(const EC_GROUP *group, EC_SCALAR *out, const EC_JACOBIAN *p); -// ec_get_x_coordinate_as_bytes writes |p|'s affine x-coordinate to |out|, which -// must have at must |max_out| bytes. It sets |*out_len| to the number of bytes +// ec_get_x_coordinate_as_bytes writes `p`'s affine x-coordinate to `out`, which +// must have at must `max_out` bytes. It sets `*out_len` to the number of bytes // written. The value is written big-endian and zero-padded to the size of the // field. This function returns one on success and zero on failure. int ec_get_x_coordinate_as_bytes(const EC_GROUP *group, uint8_t *out, @@ -427,30 +427,30 @@ const EC_JACOBIAN *p); // ec_point_byte_len returns the number of bytes in the byte representation of -// a non-infinity point in |group|, encoded according to |form|, or zero if -// |form| is invalid. +// a non-infinity point in `group`, encoded according to `form`, or zero if +// `form` is invalid. size_t ec_point_byte_len(const EC_GROUP *group, point_conversion_form_t form); -// ec_point_to_bytes encodes |point| according to |form| and writes the result -// |buf|. It returns the size of the output on success or zero on error. At most -// |max_out| bytes will be written. The buffer should be at least -// |ec_point_byte_len| long to guarantee success. +// ec_point_to_bytes encodes `point` according to `form` and writes the result +// `buf`. It returns the size of the output on success or zero on error. At most +// `max_out` bytes will be written. The buffer should be at least +// `ec_point_byte_len` long to guarantee success. size_t ec_point_to_bytes(const EC_GROUP *group, const EC_AFFINE *point, point_conversion_form_t form, uint8_t *buf, size_t max_out); -// ec_point_from_uncompressed parses |in| as a point in uncompressed form and -// sets the result to |out|. It returns one on success and zero if the input was +// ec_point_from_uncompressed parses `in` as a point in uncompressed form and +// sets the result to `out`. It returns one on success and zero if the input was // invalid. int ec_point_from_uncompressed(const EC_GROUP *group, EC_AFFINE *out, const uint8_t *in, size_t len); -// ec_set_to_safe_point sets |out| to an arbitrary point on |group|, either the +// ec_set_to_safe_point sets `out` to an arbitrary point on `group`, either the // generator or the point at infinity. This is used to guard against callers of // external APIs not checking the return value. void ec_set_to_safe_point(const EC_GROUP *group, EC_JACOBIAN *out); -// ec_affine_jacobian_equal returns one if |a| and |b| represent the same point +// ec_affine_jacobian_equal returns one if `a` and `b` represent the same point // and zero otherwise. It treats both inputs as secret. int ec_affine_jacobian_equal(const EC_GROUP *group, const EC_AFFINE *a, const EC_JACOBIAN *b); @@ -460,56 +460,56 @@ // Implementation details. struct ec_method_st { - // point_get_affine_coordinates sets |*x| and |*y| to the affine coordinates - // of |p|. Either |x| or |y| may be NULL to omit it. It returns one on success - // and zero if |p| is the point at infinity. It leaks whether |p| was the - // point at infinity, but otherwise treats |p| as secret. + // point_get_affine_coordinates sets `*x` and `*y` to the affine coordinates + // of `p`. Either `x` or `y` may be NULL to omit it. It returns one on success + // and zero if `p` is the point at infinity. It leaks whether `p` was the + // point at infinity, but otherwise treats `p` as secret. int (*point_get_affine_coordinates)(const EC_GROUP *, const bssl::EC_JACOBIAN *p, bssl::EC_FELEM *x, bssl::EC_FELEM *y); - // jacobian_to_affine_batch implements |ec_jacobian_to_affine_batch|. + // jacobian_to_affine_batch implements `ec_jacobian_to_affine_batch`. int (*jacobian_to_affine_batch)(const EC_GROUP *group, bssl::EC_AFFINE *out, const bssl::EC_JACOBIAN *in, size_t num); - // add sets |r| to |a| + |b|. + // add sets `r` to `a` + `b`. void (*add)(const EC_GROUP *group, bssl::EC_JACOBIAN *r, const bssl::EC_JACOBIAN *a, const bssl::EC_JACOBIAN *b); - // dbl sets |r| to |a| + |a|. + // dbl sets `r` to `a` + `a`. void (*dbl)(const EC_GROUP *group, bssl::EC_JACOBIAN *r, const bssl::EC_JACOBIAN *a); - // mul sets |r| to |scalar|*|p|. + // mul sets `r` to `scalar`*`p`. void (*mul)(const EC_GROUP *group, bssl::EC_JACOBIAN *r, const bssl::EC_JACOBIAN *p, const bssl::EC_SCALAR *scalar); - // mul_base sets |r| to |scalar|*generator. + // mul_base sets `r` to `scalar`*generator. void (*mul_base)(const EC_GROUP *group, bssl::EC_JACOBIAN *r, const bssl::EC_SCALAR *scalar); - // mul_batch implements |ec_mul_scalar_batch|. + // mul_batch implements `ec_mul_scalar_batch`. void (*mul_batch)(const EC_GROUP *group, bssl::EC_JACOBIAN *r, const bssl::EC_JACOBIAN *p0, const bssl::EC_SCALAR *scalar0, const bssl::EC_JACOBIAN *p1, const bssl::EC_SCALAR *scalar1, const bssl::EC_JACOBIAN *p2, const bssl::EC_SCALAR *scalar2); - // mul_public sets |r| to |g_scalar|*generator + |p_scalar|*|p|. It assumes + // mul_public sets `r` to `g_scalar`*generator + `p_scalar`*`p`. It assumes // that the inputs are public so there is no concern about leaking their // values through timing. // - // This function may be omitted if |mul_public_batch| is provided. + // This function may be omitted if `mul_public_batch` is provided. void (*mul_public)(const EC_GROUP *group, bssl::EC_JACOBIAN *r, const bssl::EC_SCALAR *g_scalar, const bssl::EC_JACOBIAN *p, const bssl::EC_SCALAR *p_scalar); - // mul_public_batch implements |ec_point_mul_scalar_public_batch|. + // mul_public_batch implements `ec_point_mul_scalar_public_batch`. int (*mul_public_batch)(const EC_GROUP *group, bssl::EC_JACOBIAN *r, const bssl::EC_SCALAR *g_scalar, const bssl::EC_JACOBIAN *points, const bssl::EC_SCALAR *scalars, size_t num); - // init_precomp implements |ec_init_precomp|. + // init_precomp implements `ec_init_precomp`. int (*init_precomp)(const EC_GROUP *group, bssl::EC_PRECOMP *out, const bssl::EC_JACOBIAN *p); - // mul_precomp implements |ec_point_mul_scalar_precomp|. + // mul_precomp implements `ec_point_mul_scalar_precomp`. void (*mul_precomp)(const EC_GROUP *group, bssl::EC_JACOBIAN *r, const bssl::EC_PRECOMP *p0, const bssl::EC_SCALAR *scalar0, @@ -518,18 +518,18 @@ const bssl::EC_PRECOMP *p2, const bssl::EC_SCALAR *scalar2); - // scalar_inv0_montgomery implements |ec_scalar_inv0_montgomery|. + // scalar_inv0_montgomery implements `ec_scalar_inv0_montgomery`. void (*scalar_inv0_montgomery)(const EC_GROUP *group, bssl::EC_SCALAR *out, const bssl::EC_SCALAR *in); // scalar_to_montgomery_inv_vartime implements - // |ec_scalar_to_montgomery_inv_vartime|. + // `ec_scalar_to_montgomery_inv_vartime`. int (*scalar_to_montgomery_inv_vartime)(const EC_GROUP *group, bssl::EC_SCALAR *out, const bssl::EC_SCALAR *in); - // cmp_x_coordinate compares the x (affine) coordinate of |p|, mod the group - // order, with |r|. It returns one if the values match and zero if |p| is the + // cmp_x_coordinate compares the x (affine) coordinate of `p`, mod the group + // order, with `r`. It returns one if the values match and zero if `p` is the // point at infinity of the values do not match. int (*cmp_x_coordinate)(const EC_GROUP *group, const bssl::EC_JACOBIAN *p, const bssl::EC_SCALAR *r); @@ -542,12 +542,12 @@ BSSL_NAMESPACE_END struct ec_point_st { - // group is an owning reference to |group|, unless this is - // |group->generator|. + // group is an owning reference to `group`, unless this is + // `group->generator`. EC_GROUP *group; - // raw is the group-specific point data. Functions that take |EC_POINT| - // typically check consistency with |EC_GROUP| while functions that take - // |EC_JACOBIAN| do not. Thus accesses to this field should be externally + // raw is the group-specific point data. Functions that take `EC_POINT` + // typically check consistency with `EC_GROUP` while functions that take + // `EC_JACOBIAN` do not. Thus accesses to this field should be externally // checked for consistency. bssl::EC_JACOBIAN raw; } /* EC_POINT */; @@ -555,9 +555,9 @@ struct ec_group_st { const EC_METHOD *meth; - // Unlike all other |EC_POINT|s, |generator| does not own |generator->group| + // Unlike all other `EC_POINT`s, `generator` does not own `generator->group` // to avoid a reference cycle. Additionally, Z is guaranteed to be one, so X - // and Y are suitable for use as an |EC_AFFINE|. Before |has_order| is set, Z + // and Y are suitable for use as an `EC_AFFINE`. Before `has_order` is set, Z // is one, but X and Y are uninitialized. EC_POINT generator; @@ -578,14 +578,14 @@ uint8_t oid[9]; uint8_t oid_len; - // a_is_minus3 is one if |a| is -3 mod |field| and zero otherwise. Point + // a_is_minus3 is one if `a` is -3 mod `field` and zero otherwise. Point // arithmetic is optimized for -3. int a_is_minus3; - // has_order is one if |generator| and |order| have been initialized. + // has_order is one if `generator` and `order` have been initialized. int has_order; - // field_greater_than_order is one if |field| is greater than |order| and zero + // field_greater_than_order is one if `field` is greater than `order` and zero // otherwise. int field_greater_than_order; } /* EC_GROUP */; @@ -620,7 +620,7 @@ const EC_PRECOMP *p2, const EC_SCALAR *scalar2); // ec_compute_wNAF writes the modified width-(w+1) Non-Adjacent Form (wNAF) of -// |scalar| to |out|. |out| must have room for |bits| + 1 elements, each of +// `scalar` to `out`. `out` must have room for `bits` + 1 elements, each of // which will be either zero or odd with an absolute value less than 2^w // satisfying // scalar = \sum_j out[j]*2^j @@ -670,8 +670,8 @@ // x86-64 optimized P256. See http://eprint.iacr.org/2013/816. const EC_METHOD *EC_GFp_nistz256_method(); -// An EC_WRAPPED_SCALAR is an |EC_SCALAR| with a parallel |BIGNUM| -// representation. It exists to support the |EC_KEY_get0_private_key| API. +// An EC_WRAPPED_SCALAR is an `EC_SCALAR` with a parallel `BIGNUM` +// representation. It exists to support the `EC_KEY_get0_private_key` API. typedef struct { BIGNUM bignum; EC_SCALAR scalar; @@ -683,9 +683,9 @@ EC_GROUP *group = nullptr; - // Ideally |pub_key| would be an |EC_AFFINE| so serializing it does not pay an - // inversion each time, but the |EC_KEY_get0_public_key| API implies public - // keys are stored in an |EC_POINT|-compatible form. + // Ideally `pub_key` would be an `EC_AFFINE` so serializing it does not pay an + // inversion each time, but the `EC_KEY_get0_public_key` API implies public + // keys are stored in an `EC_POINT`-compatible form. EC_POINT *pub_key = nullptr; bssl::EC_WRAPPED_SCALAR *priv_key = nullptr;
diff --git a/crypto/fipsmodule/ec/p256-nistz.h b/crypto/fipsmodule/ec/p256-nistz.h index c696388..43da01c 100644 --- a/crypto/fipsmodule/ec/p256-nistz.h +++ b/crypto/fipsmodule/ec/p256-nistz.h
@@ -42,17 +42,17 @@ // P-256 field operations. // // An element mod P in P-256 is represented as a little-endian array of -// |P256_LIMBS| |BN_ULONG|s, spanning the full range of values. +// `P256_LIMBS` `BN_ULONG`s, spanning the full range of values. // // The following functions take fully-reduced inputs mod P and give // fully-reduced outputs. They may be used in-place. #define P256_LIMBS (256 / BN_BITS2) -// ecp_nistz256_neg sets |res| to -|a| mod P. +// ecp_nistz256_neg sets `res` to -`a` mod P. void ecp_nistz256_neg(BN_ULONG res[P256_LIMBS], const BN_ULONG a[P256_LIMBS]); -// ecp_nistz256_mul_mont sets |res| to |a| * |b| * 2^-256 mod P. +// ecp_nistz256_mul_mont sets `res` to `a` * `b` * 2^-256 mod P. #if defined(OPENSSL_X86_64) void ecp_nistz256_mul_mont_nohw(BN_ULONG res[P256_LIMBS], const BN_ULONG a[P256_LIMBS], @@ -66,7 +66,7 @@ const BN_ULONG b[P256_LIMBS]); #endif -// ecp_nistz256_sqr_mont sets |res| to |a| * |a| * 2^-256 mod P. +// ecp_nistz256_sqr_mont sets `res` to `a` * `a` * 2^-256 mod P. #if defined(OPENSSL_X86_64) void ecp_nistz256_sqr_mont_nohw(BN_ULONG res[P256_LIMBS], const BN_ULONG a[P256_LIMBS]); @@ -83,8 +83,8 @@ // The following functions compute modulo N, where N is the order of P-256. They // take fully-reduced inputs and give fully-reduced outputs. -// ecp_nistz256_ord_mul_mont sets |res| to |a| * |b| where inputs and outputs -// are in Montgomery form. That is, |res| is |a| * |b| * 2^-256 mod N. +// ecp_nistz256_ord_mul_mont sets `res` to `a` * `b` where inputs and outputs +// are in Montgomery form. That is, `res` is `a` * `b` * 2^-256 mod N. #if defined(OPENSSL_X86_64) void ecp_nistz256_ord_mul_mont_nohw(BN_ULONG res[P256_LIMBS], const BN_ULONG a[P256_LIMBS], @@ -98,9 +98,9 @@ const BN_ULONG b[P256_LIMBS]); #endif -// ecp_nistz256_ord_sqr_mont sets |res| to |a|^(2*|rep|) where inputs and -// outputs are in Montgomery form. That is, |res| is -// (|a| * 2^-256)^(2*|rep|) * 2^256 mod N. +// ecp_nistz256_ord_sqr_mont sets `res` to `a`^(2*`rep`) where inputs and +// outputs are in Montgomery form. That is, `res` is +// (`a` * 2^-256)^(2*`rep`) * 2^256 mod N. #if defined(OPENSSL_X86_64) void ecp_nistz256_ord_sqr_mont_nohw(BN_ULONG res[P256_LIMBS], const BN_ULONG a[P256_LIMBS], BN_ULONG rep); @@ -137,8 +137,8 @@ BN_ULONG Y[P256_LIMBS]; } P256_POINT_AFFINE; -// ecp_nistz256_select_w5 sets |*val| to |in_t[index-1]| if 1 <= |index| <= 16 -// and all zeros (the point at infinity) if |index| is 0. This is done in +// ecp_nistz256_select_w5 sets `*val` to `in_t[index-1]` if 1 <= `index` <= 16 +// and all zeros (the point at infinity) if `index` is 0. This is done in // constant time. #if defined(OPENSSL_X86_64) void ecp_nistz256_select_w5_nohw(P256_POINT *val, const P256_POINT in_t[16], @@ -150,8 +150,8 @@ int index); #endif -// ecp_nistz256_select_w7 sets |*val| to |in_t[index-1]| if 1 <= |index| <= 64 -// and all zeros (the point at infinity) if |index| is 0. This is done in +// ecp_nistz256_select_w7 sets `*val` to `in_t[index-1]` if 1 <= `index` <= 64 +// and all zeros (the point at infinity) if `index` is 0. This is done in // constant time. #if defined(OPENSSL_X86_64) void ecp_nistz256_select_w7_nohw(P256_POINT_AFFINE *val, @@ -163,7 +163,7 @@ const P256_POINT_AFFINE in_t[64], int index); #endif -// ecp_nistz256_point_double sets |r| to |a| doubled. +// ecp_nistz256_point_double sets `r` to `a` doubled. #if defined(OPENSSL_X86_64) void ecp_nistz256_point_double_nohw(P256_POINT *r, const P256_POINT *a); void ecp_nistz256_point_double_adx(P256_POINT *r, const P256_POINT *a); @@ -171,7 +171,7 @@ void ecp_nistz256_point_double(P256_POINT *r, const P256_POINT *a); #endif -// ecp_nistz256_point_add adds |a| to |b| and places the result in |r|. +// ecp_nistz256_point_add adds `a` to `b` and places the result in `r`. #if defined(OPENSSL_X86_64) void ecp_nistz256_point_add_nohw(P256_POINT *r, const P256_POINT *a, const P256_POINT *b); @@ -182,8 +182,8 @@ const P256_POINT *b); #endif -// ecp_nistz256_point_add_affine adds |a| to |b| and places the result in -// |r|. |a| and |b| must not represent the same point unless they are both +// ecp_nistz256_point_add_affine adds `a` to `b` and places the result in +// `r`. `a` and `b` must not represent the same point unless they are both // infinity. #if defined(OPENSSL_X86_64) void ecp_nistz256_point_add_affine_adx(P256_POINT *r, const P256_POINT *a,
diff --git a/crypto/fipsmodule/ecdsa/internal.h b/crypto/fipsmodule/ecdsa/internal.h index 622b688..90cf9c5 100644 --- a/crypto/fipsmodule/ecdsa/internal.h +++ b/crypto/fipsmodule/ecdsa/internal.h
@@ -26,21 +26,21 @@ // fixed-width, big-endian format from IEEE P1363. #define ECDSA_MAX_FIXED_LEN (2 * EC_MAX_BYTES) -// ecdsa_sign_fixed behaves like |ECDSA_sign| but uses the fixed-width, +// ecdsa_sign_fixed behaves like `ECDSA_sign` but uses the fixed-width, // big-endian format from IEEE P1363. int ecdsa_sign_fixed(const uint8_t *digest, size_t digest_len, uint8_t *sig, size_t *out_sig_len, size_t max_sig_len, const EC_KEY *key); // ecdsa_sign_fixed_with_nonce_for_known_answer_test behaves like -// |ecdsa_sign_fixed| but takes a caller-supplied nonce. This function is used +// `ecdsa_sign_fixed` but takes a caller-supplied nonce. This function is used // as part of known-answer tests in the FIPS module. int ecdsa_sign_fixed_with_nonce_for_known_answer_test( const uint8_t *digest, size_t digest_len, uint8_t *sig, size_t *out_sig_len, size_t max_sig_len, const EC_KEY *key, const uint8_t *nonce, size_t nonce_len); -// ecdsa_verify_fixed behaves like |ECDSA_verify| but uses the fixed-width, +// ecdsa_verify_fixed behaves like `ECDSA_verify` but uses the fixed-width, // big-endian format from IEEE P1363. int ecdsa_verify_fixed(const uint8_t *digest, size_t digest_len, const uint8_t *sig, size_t sig_len, const EC_KEY *key);
diff --git a/crypto/fipsmodule/keccak/internal.h b/crypto/fipsmodule/keccak/internal.h index ff10c44..4d11b48 100644 --- a/crypto/fipsmodule/keccak/internal.h +++ b/crypto/fipsmodule/keccak/internal.h
@@ -45,28 +45,28 @@ size_t squeeze_offset; }; -// BORINGSSL_keccak hashes |in_len| bytes from |in| and writes |out_len| bytes -// of output to |out|. If the |config| specifies a fixed-output function, like -// SHA3-256, then |out_len| must be the correct length for that function. +// BORINGSSL_keccak hashes `in_len` bytes from `in` and writes `out_len` bytes +// of output to `out`. If the `config` specifies a fixed-output function, like +// SHA3-256, then `out_len` must be the correct length for that function. OPENSSL_EXPORT void BORINGSSL_keccak(uint8_t *out, size_t out_len, const uint8_t *in, size_t in_len, enum boringssl_keccak_config_t config); -// BORINGSSL_keccak_init prepares |ctx| for absorbing. If the |config| specifies +// BORINGSSL_keccak_init prepares `ctx` for absorbing. If the `config` specifies // a fixed-output function, like SHA3-256, then the output must be squeezed in a -// single call to |BORINGSSL_keccak_squeeze|. In that case, it is recommended to -// use |BORINGSSL_keccak| if the input can be absorbed in a single call. +// single call to `BORINGSSL_keccak_squeeze`. In that case, it is recommended to +// use `BORINGSSL_keccak` if the input can be absorbed in a single call. OPENSSL_EXPORT void BORINGSSL_keccak_init( struct BORINGSSL_keccak_st *ctx, enum boringssl_keccak_config_t config); -// BORINGSSL_keccak_absorb absorbs |in_len| bytes from |in|. +// BORINGSSL_keccak_absorb absorbs `in_len` bytes from `in`. OPENSSL_EXPORT void BORINGSSL_keccak_absorb(struct BORINGSSL_keccak_st *ctx, const uint8_t *in, size_t in_len); -// BORINGSSL_keccak_squeeze writes |out_len| bytes to |out| from |ctx|. If the -// configuration previously passed in |BORINGSSL_keccak_init| specifies a -// fixed-output function, then a single call to |BORINGSSL_keccak_squeeze| is -// allowed, where |out_len| must be the correct length for that function. +// BORINGSSL_keccak_squeeze writes `out_len` bytes to `out` from `ctx`. If the +// configuration previously passed in `BORINGSSL_keccak_init` specifies a +// fixed-output function, then a single call to `BORINGSSL_keccak_squeeze` is +// allowed, where `out_len` must be the correct length for that function. OPENSSL_EXPORT void BORINGSSL_keccak_squeeze(struct BORINGSSL_keccak_st *ctx, uint8_t *out, size_t out_len); @@ -84,8 +84,8 @@ struct BORINGSSL_keccak_st ctx[2], uint8_t *outs[2], size_t out_len); // BORINGSSL_keccak_short_x2 performs BORINGSSL_keccak in parallel on two -// same-length strings with same-length outputs. |in_len| must be less than 72 -// (or actually |rate_bytes|). +// same-length strings with same-length outputs. `in_len` must be less than 72 +// (or actually `rate_bytes`). OPENSSL_EXPORT void BORINGSSL_keccak_short_x2( uint8_t *outs[2], size_t out_len, const uint8_t *ins[2], size_t in_len, enum boringssl_keccak_config_t config);
diff --git a/crypto/fipsmodule/rand/internal.h b/crypto/fipsmodule/rand/internal.h index cd1fc62..8895b96 100644 --- a/crypto/fipsmodule/rand/internal.h +++ b/crypto/fipsmodule/rand/internal.h
@@ -25,7 +25,7 @@ BSSL_NAMESPACE_BEGIN // rand_fork_unsafe_buffering_enabled returns whether fork-unsafe buffering has -// been enabled via |RAND_enable_fork_unsafe_buffering|. +// been enabled via `RAND_enable_fork_unsafe_buffering`. int rand_fork_unsafe_buffering_enabled(); BSSL_NAMESPACE_END @@ -43,13 +43,13 @@ BSSL_NAMESPACE_BEGIN -// CTR_DRBG_init initialises |*drbg| given |entropy_len| bytes of entropy in -// |entropy| and, optionally, a personalization string up to -// |CTR_DRBG_SEED_LEN| bytes in length. It returns one on success and zero on +// CTR_DRBG_init initialises `*drbg` given `entropy_len` bytes of entropy in +// `entropy` and, optionally, a personalization string up to +// `CTR_DRBG_SEED_LEN` bytes in length. It returns one on success and zero on // error. // -// If `df` is false then `entropy_len` must be |CTR_DRBG_ENTROPY_LEN| and -// |nonce| must be nullptr. +// If `df` is false then `entropy_len` must be `CTR_DRBG_ENTROPY_LEN` and +// `nonce` must be nullptr. OPENSSL_EXPORT int CTR_DRBG_init(CTR_DRBG_STATE *drbg, int df, const uint8_t *entropy, size_t entropy_len, const uint8_t nonce[CTR_DRBG_NONCE_LEN], @@ -78,11 +78,11 @@ } // CRYPTO_rdrand writes eight bytes of random data from the hardware RNG to -// |out|. It returns one on success or zero on hardware failure. +// `out`. It returns one on success or zero on hardware failure. extern "C" int CRYPTO_rdrand(uint8_t out[8]); -// CRYPTO_rdrand_multiple8_buf fills |len| bytes at |buf| with random data from -// the hardware RNG. The |len| argument must be a multiple of eight. It returns +// CRYPTO_rdrand_multiple8_buf fills `len` bytes at `buf` with random data from +// the hardware RNG. The `len` argument must be a multiple of eight. It returns // one on success and zero on hardware failure. extern "C" int CRYPTO_rdrand_multiple8_buf(uint8_t *buf, size_t len);
diff --git a/crypto/fipsmodule/rsa/internal.h b/crypto/fipsmodule/rsa/internal.h index 3a0daf5..ebb70c3 100644 --- a/crypto/fipsmodule/rsa/internal.h +++ b/crypto/fipsmodule/rsa/internal.h
@@ -31,7 +31,7 @@ // TODO(crbug.com/42290480): Raise this limit. 512-bit RSA was factored in 1999. #define OPENSSL_RSA_MIN_MODULUS_BITS 512 -// TODO(davidben): This is inside BCM because |RSA| is inside BCM, but BCM never +// TODO(davidben): This is inside BCM because `RSA` is inside BCM, but BCM never // uses this. Split the RSA type in two. enum rsa_pss_params_t { // No parameters. @@ -67,19 +67,19 @@ Mutex lock; // Used to cache montgomery values. The creation of these values is protected - // by |lock|. + // by `lock`. UniquePtr<BN_MONT_CTX> mont_n; UniquePtr<BN_MONT_CTX> mont_p; UniquePtr<BN_MONT_CTX> mont_q; - // The following fields are copies of |d|, |dmp1|, and |dmq1|, respectively, + // The following fields are copies of `d`, `dmp1`, and `dmq1`, respectively, // but with the correct widths to prevent side channels. These must use // separate copies due to threading concerns caused by OpenSSL's API // mistakes. See https://github.com/openssl/openssl/issues/5158 and - // the |freeze_private_key| implementation. + // the `freeze_private_key` implementation. UniquePtr<BIGNUM> d_fixed, dmp1_fixed, dmq1_fixed; - // iqmp_mont is q^-1 mod p in Montgomery form, using |mont_p|. + // iqmp_mont is q^-1 mod p in Montgomery form, using `mont_p`. UniquePtr<BIGNUM> iqmp_mont; // pss_params is the RSA-PSS parameters associated with the key. This is not @@ -118,26 +118,26 @@ int RSA_padding_add_none(uint8_t *to, size_t to_len, const uint8_t *from, size_t from_len); -// rsa_check_public_key checks that |rsa|'s public modulus and exponent are +// rsa_check_public_key checks that `rsa`'s public modulus and exponent are // within DoS bounds. int rsa_check_public_key(const RSA *rsa); // rsa_private_transform_no_self_test calls either the method-specific -// |private_transform| function (if given) or the generic one. See the comment -// for |private_transform| in |rsa_meth_st|. +// `private_transform` function (if given) or the generic one. See the comment +// for `private_transform` in `rsa_meth_st`. int rsa_private_transform_no_self_test(RSA *rsa, uint8_t *out, const uint8_t *in, size_t len); -// rsa_private_transform acts the same as |rsa_private_transform_no_self_test| +// rsa_private_transform acts the same as `rsa_private_transform_no_self_test` // but, in FIPS mode, performs an RSA self test before calling the default RSA // implementation. int rsa_private_transform(RSA *rsa, uint8_t *out, const uint8_t *in, size_t len); -// rsa_invalidate_key is called after |rsa| has been mutated, to invalidate +// rsa_invalidate_key is called after `rsa` has been mutated, to invalidate // fields derived from the original structure. This function assumes exclusive -// access to |rsa|. In particular, no other thread may be concurrently signing, -// etc., with |rsa|. +// access to `rsa`. In particular, no other thread may be concurrently signing, +// etc., with `rsa`. void rsa_invalidate_key(RSA *rsa);
diff --git a/crypto/fipsmodule/service_indicator/internal.h b/crypto/fipsmodule/service_indicator/internal.h index 064618e..a46b1e0 100644 --- a/crypto/fipsmodule/service_indicator/internal.h +++ b/crypto/fipsmodule/service_indicator/internal.h
@@ -20,21 +20,21 @@ BSSL_NAMESPACE_BEGIN -// FIPS_service_indicator_before_call and |FIPS_service_indicator_after_call| +// FIPS_service_indicator_before_call and `FIPS_service_indicator_after_call` // both currently return the same local thread counter which is slowly // incremented whenever approved services are called. The -// |CALL_SERVICE_AND_CHECK_APPROVED| macro is strongly recommended over calling +// `CALL_SERVICE_AND_CHECK_APPROVED` macro is strongly recommended over calling // these functions directly. // -// |FIPS_service_indicator_before_call| is intended to be called immediately -// before an approved service, while |FIPS_service_indicator_after_call| should +// `FIPS_service_indicator_before_call` is intended to be called immediately +// before an approved service, while `FIPS_service_indicator_after_call` should // be called immediately after. If the values returned from these two functions // are not equal, this means that the service called in between is deemed to be // approved. If the values are still the same, this means the counter has not // been incremented, and the service called is not approved for FIPS. // -// In non-FIPS builds, |FIPS_service_indicator_before_call| always returns zero -// and |FIPS_service_indicator_after_call| always returns one. Thus calls always +// In non-FIPS builds, `FIPS_service_indicator_before_call` always returns zero +// and `FIPS_service_indicator_after_call` always returns one. Thus calls always // appear to be approved. This is intended to simplify testing. OPENSSL_EXPORT uint64_t FIPS_service_indicator_before_call(); OPENSSL_EXPORT uint64_t FIPS_service_indicator_after_call(); @@ -45,11 +45,11 @@ // invoked. void FIPS_service_indicator_update_state(); -// FIPS_service_indicator_lock_state and |FIPS_service_indicator_unlock_state| -// stop |FIPS_service_indicator_update_state| from actually updating the service +// FIPS_service_indicator_lock_state and `FIPS_service_indicator_unlock_state` +// stop `FIPS_service_indicator_update_state` from actually updating the service // indicator. This is used when a primitive calls a potentially approved // primitive to avoid false positives. For example, just because a key -// generation calls |BCM_rand_bytes| (and thus the approved DRBG) doesn't mean +// generation calls `BCM_rand_bytes` (and thus the approved DRBG) doesn't mean // that the key generation operation itself is approved. // // This lock nests: i.e. locking twice is fine so long as each lock is paired @@ -57,7 +57,7 @@ void FIPS_service_indicator_lock_state(); void FIPS_service_indicator_unlock_state(); -// The following functions may call |FIPS_service_indicator_update_state| if +// The following functions may call `FIPS_service_indicator_update_state` if // their parameter specifies an approved operation. void AEAD_GCM_verify_service_indicator(const EVP_AEAD_CTX *ctx);
diff --git a/crypto/hrss/internal.h b/crypto/hrss/internal.h index 78d385b..185d79a 100644 --- a/crypto/hrss/internal.h +++ b/crypto/hrss/internal.h
@@ -40,7 +40,7 @@ // On x86-64, we can use the AVX2 code from [HRSS]. (The authors have given // explicit permission for this and signed a CLA.) However it's 57KB of object -// code, so it's not used if |OPENSSL_SMALL| is defined. +// code, so it's not used if `OPENSSL_SMALL` is defined. #if !defined(OPENSSL_NO_ASM) && !defined(OPENSSL_SMALL) && \ defined(OPENSSL_X86_64) && defined(OPENSSL_LINUX) #define POLY_RQ_MUL_ASM
diff --git a/crypto/internal.h b/crypto/internal.h index 7c4b509..7c835fa 100644 --- a/crypto/internal.h +++ b/crypto/internal.h
@@ -76,7 +76,7 @@ #define NEED_CPUID // OPENSSL_cpuid_setup initializes the platform-specific feature cache. This -// function should not be called directly. Call |OPENSSL_init_cpuid| instead. +// function should not be called directly. Call `OPENSSL_init_cpuid` instead. void OPENSSL_cpuid_setup(); // OPENSSL_init_cpuid initializes the platform-specific feature cache, if @@ -89,7 +89,7 @@ #if (defined(OPENSSL_ARM) || defined(OPENSSL_AARCH64)) && \ !defined(OPENSSL_STATIC_ARMCAP) // OPENSSL_get_armcap_pointer_for_test returns a pointer to -// |OPENSSL_armcap_P| for unit tests. Any modifications to the value must be +// `OPENSSL_armcap_P` for unit tests. Any modifications to the value must be // made before any other function call in BoringSSL. OPENSSL_EXPORT uint32_t *OPENSSL_get_armcap_pointer_for_test(); #endif @@ -113,7 +113,7 @@ #endif #endif -// GCC-like compilers indicate SSE2 with |__SSE2__|. MSVC leaves the caller to +// GCC-like compilers indicate SSE2 with `__SSE2__`. MSVC leaves the caller to // know that x86_64 has SSE2, and uses _M_IX86_FP to indicate SSE2 on x86. // https://learn.microsoft.com/en-us/cpp/preprocessor/predefined-macros?view=msvc-170 #if defined(__SSE2__) || defined(_M_AMD64) || defined(_M_X64) || \ @@ -127,7 +127,7 @@ #endif // For convenience in testing the fallback code, we allow disabling SSE2 -// intrinsics via |OPENSSL_NO_SSE2_FOR_TESTING|. We require SSE2 on x86 and +// intrinsics via `OPENSSL_NO_SSE2_FOR_TESTING`. We require SSE2 on x86 and // x86_64, so we would otherwise need to test such code on a non-x86 platform. // // This does not remove the above requirement for SSE2 support with assembly @@ -151,7 +151,7 @@ OPENSSL_EXPORT void OPENSSL_reset_malloc_counter_for_testing(); // OPENSSL_disable_malloc_failures_for_testing, when malloc testing is enabled, -// disables simulated malloc failures. Calls to |OPENSSL_malloc| will not +// disables simulated malloc failures. Calls to `OPENSSL_malloc` will not // increment the malloc counter or synthesize failures. This may be used to skip // simulating malloc failures in some region of code. OPENSSL_EXPORT void OPENSSL_disable_malloc_failures_for_testing(); @@ -174,10 +174,10 @@ // Pointer utility functions. -// buffers_alias returns one if |a| and |b| alias and zero otherwise. +// buffers_alias returns one if `a` and `b` alias and zero otherwise. inline int buffers_alias(const void *a, size_t a_bytes, const void *b, size_t b_bytes) { - // Cast |a| and |b| to integers. In C, pointer comparisons between unrelated + // Cast `a` and `b` to integers. In C, pointer comparisons between unrelated // objects are undefined whereas pointer to integer conversions are merely // implementation-defined. We assume the implementation defined it in a sane // way. @@ -186,22 +186,22 @@ return a_u + a_bytes > b_u && b_u + b_bytes > a_u; } -// spans_alias returns one if |a| and |b| alias, and zero otherwise. +// spans_alias returns one if `a` and `b` alias, and zero otherwise. template <typename T> inline int spans_alias(Span<const T> a, Span<const T> b) { return buffers_alias(a.data(), a.size() * sizeof(T), b.data(), b.size() * sizeof(T)); } -// align_pointer returns |ptr|, advanced to |alignment|. |alignment| must be a -// power of two, and |ptr| must have at least |alignment - 1| bytes of scratch +// align_pointer returns `ptr`, advanced to `alignment`. `alignment` must be a +// power of two, and `ptr` must have at least `alignment - 1` bytes of scratch // space. inline void *align_pointer(void *ptr, size_t alignment) { - // |alignment| must be a power of two. + // `alignment` must be a power of two. assert(alignment != 0 && (alignment & (alignment - 1)) == 0); - // Instead of aligning |ptr| as a |uintptr_t| and casting back, compute the + // Instead of aligning `ptr` as a `uintptr_t` and casting back, compute the // offset and advance in pointer space. C guarantees that casting from pointer - // to |uintptr_t| and back gives the same pointer, but general + // to `uintptr_t` and back gives the same pointer, but general // integer-to-pointer conversions are implementation-defined. GCC does define // it in the useful way, but this makes fewer assumptions. uintptr_t offset = (0u - (uintptr_t)ptr) & (alignment - 1); @@ -229,10 +229,10 @@ // c = constant_time_select_w(lt, a, b); // crypto_word_t is the type that most constant-time functions use. Ideally we -// would like it to be |size_t|, but NaCl builds in 64-bit mode with 32-bit -// pointers, which means that |size_t| can be 32 bits when |BN_ULONG| is 64 +// would like it to be `size_t`, but NaCl builds in 64-bit mode with 32-bit +// pointers, which means that `size_t` can be 32 bits when `BN_ULONG` is 64 // bits. Since we want to be able to do constant-time operations on a -// |BN_ULONG|, |crypto_word_t| is defined as an unsigned value with the native +// `BN_ULONG`, `crypto_word_t` is defined as an unsigned value with the native // word length. #if defined(OPENSSL_64_BIT) typedef uint64_t crypto_word_t; @@ -247,11 +247,11 @@ #define CONSTTIME_TRUE_8 ((uint8_t)0xff) #define CONSTTIME_FALSE_8 ((uint8_t)0) -// value_barrier_w returns |a|, but prevents GCC and Clang from reasoning about +// value_barrier_w returns `a`, but prevents GCC and Clang from reasoning about // the returned value. This is used to mitigate compilers undoing constant-time // code, until we can express our requirements directly in the language. // -// Note the compiler is aware that |value_barrier_w| has no side effects and +// Note the compiler is aware that `value_barrier_w` has no side effects and // always has the same output for a given input. This allows it to eliminate // dead code, move computations across loops, and vectorize. inline crypto_word_t value_barrier_w(crypto_word_t a) { @@ -261,7 +261,7 @@ return a; } -// value_barrier_u32 behaves like |value_barrier_w| but takes a |uint32_t|. +// value_barrier_u32 behaves like `value_barrier_w` but takes a `uint32_t`. inline uint32_t value_barrier_u32(uint32_t a) { #if defined(__GNUC__) || defined(__clang__) __asm__("" : "+r"(a) : /* no inputs */); @@ -269,7 +269,7 @@ return a; } -// value_barrier_u64 behaves like |value_barrier_w| but takes a |uint64_t|. +// value_barrier_u64 behaves like `value_barrier_w` but takes a `uint64_t`. inline uint64_t value_barrier_u64(uint64_t a) { #if defined(__GNUC__) || defined(__clang__) __asm__("" : "+r"(a) : /* no inputs */); @@ -277,7 +277,7 @@ return a; } -// |value_barrier_u8| could be defined as above, but compilers other than +// `value_barrier_u8` could be defined as above, but compilers other than // clang seem to still materialize 0x00..00MM instead of reusing 0x??..??MM. // constant_time_msb_w returns the given value with the MSB copied to all the @@ -321,7 +321,7 @@ return constant_time_msb_w(a ^ ((a ^ b) | ((a - b) ^ a))); } -// constant_time_lt_8 acts like |constant_time_lt_w| but returns an 8-bit +// constant_time_lt_8 acts like `constant_time_lt_w` but returns an 8-bit // mask. inline uint8_t constant_time_lt_8(crypto_word_t a, crypto_word_t b) { return (uint8_t)(constant_time_lt_w(a, b)); @@ -332,7 +332,7 @@ return ~constant_time_lt_w(a, b); } -// constant_time_ge_8 acts like |constant_time_ge_w| but returns an 8-bit +// constant_time_ge_8 acts like `constant_time_ge_w` but returns an 8-bit // mask. inline uint8_t constant_time_ge_8(crypto_word_t a, crypto_word_t b) { return (uint8_t)(constant_time_ge_w(a, b)); @@ -353,7 +353,7 @@ return constant_time_msb_w(~a & (a - 1)); } -// constant_time_is_zero_8 acts like |constant_time_is_zero_w| but returns an +// constant_time_is_zero_8 acts like `constant_time_is_zero_w` but returns an // 8-bit mask. inline uint8_t constant_time_is_zero_8(crypto_word_t a) { return (uint8_t)(constant_time_is_zero_w(a)); @@ -364,27 +364,27 @@ return constant_time_is_zero_w(a ^ b); } -// constant_time_eq_8 acts like |constant_time_eq_w| but returns an 8-bit +// constant_time_eq_8 acts like `constant_time_eq_w` but returns an 8-bit // mask. inline uint8_t constant_time_eq_8(crypto_word_t a, crypto_word_t b) { return (uint8_t)(constant_time_eq_w(a, b)); } -// constant_time_eq_int acts like |constant_time_eq_w| but works on int +// constant_time_eq_int acts like `constant_time_eq_w` but works on int // values. inline crypto_word_t constant_time_eq_int(int a, int b) { return constant_time_eq_w((crypto_word_t)(a), (crypto_word_t)(b)); } -// constant_time_eq_int_8 acts like |constant_time_eq_int| but returns an 8-bit +// constant_time_eq_int_8 acts like `constant_time_eq_int` but returns an 8-bit // mask. inline uint8_t constant_time_eq_int_8(int a, int b) { return constant_time_eq_8((crypto_word_t)(a), (crypto_word_t)(b)); } -// constant_time_select_w returns (mask & a) | (~mask & b). When |mask| is all +// constant_time_select_w returns (mask & a) | (~mask & b). When `mask` is all // 1s or all 0s (as returned by the methods above), the select methods return -// either |a| (if |mask| is nonzero) or |b| (if |mask| is zero). +// either `a` (if `mask` is nonzero) or `b` (if `mask` is zero). inline crypto_word_t constant_time_select_w(crypto_word_t mask, crypto_word_t a, crypto_word_t b) { // Clang recognizes this pattern as a select. While it usually transforms it @@ -396,28 +396,28 @@ return (mask & a) | (~mask & b); } -// constant_time_select_8 acts like |constant_time_select| but operates on +// constant_time_select_8 acts like `constant_time_select` but operates on // 8-bit values. inline uint8_t constant_time_select_8(crypto_word_t mask, uint8_t a, uint8_t b) { - // |mask| is a word instead of |uint8_t| to avoid materializing 0x000..0MM - // Making both |mask| and its value barrier |uint8_t| would allow the compiler + // `mask` is a word instead of `uint8_t` to avoid materializing 0x000..0MM + // Making both `mask` and its value barrier `uint8_t` would allow the compiler // to materialize 0x????..?MM instead, but only clang is that clever. // However, vectorization of bitwise operations seems to work better on - // |uint8_t| than a mix of |uint64_t| and |uint8_t|, so |m| is cast to - // |uint8_t| after the value barrier but before the bitwise operations. + // `uint8_t` than a mix of `uint64_t` and `uint8_t`, so `m` is cast to + // `uint8_t` after the value barrier but before the bitwise operations. uint8_t m = value_barrier_w(mask); return (m & a) | (~m & b); } -// constant_time_select_int acts like |constant_time_select| but operates on +// constant_time_select_int acts like `constant_time_select` but operates on // ints. inline int constant_time_select_int(crypto_word_t mask, int a, int b) { return static_cast<int>(constant_time_select_w( mask, static_cast<crypto_word_t>(a), static_cast<crypto_word_t>(b))); } -// constant_time_select_32 acts like |constant_time_select| but operates on +// constant_time_select_32 acts like `constant_time_select` but operates on // 32-bit values. inline uint32_t constant_time_select_32(crypto_word_t mask, uint32_t a, uint32_t b) { @@ -425,9 +425,9 @@ constant_time_select_w(mask, crypto_word_t{a}, crypto_word_t{b})); } -// constant_time_conditional_memcpy copies |n| bytes from |src| to |dst| if -// |mask| is 0xff..ff and does nothing if |mask| is 0. The |n|-byte memory -// ranges at |dst| and |src| must not overlap, as when calling |memcpy|. +// constant_time_conditional_memcpy copies `n` bytes from `src` to `dst` if +// `mask` is 0xff..ff and does nothing if `mask` is 0. The `n`-byte memory +// ranges at `dst` and `src` must not overlap, as when calling `memcpy`. inline void constant_time_conditional_memcpy(void *dst, const void *src, const size_t n, const crypto_word_t mask) { @@ -439,9 +439,9 @@ } } -// constant_time_conditional_memxor xors |n| bytes from |src| to |dst| if -// |mask| is 0xff..ff and does nothing if |mask| is 0. The |n|-byte memory -// ranges at |dst| and |src| must not overlap, as when calling |memcpy|. +// constant_time_conditional_memxor xors `n` bytes from `src` to `dst` if +// `mask` is 0xff..ff and does nothing if `mask` is 0. The `n`-byte memory +// ranges at `dst` and `src` must not overlap, as when calling `memcpy`. inline void constant_time_conditional_memxor(void *dst, const void *src, size_t n, const crypto_word_t mask) { @@ -495,9 +495,9 @@ #endif // BORINGSSL_CONSTANT_TIME_VALIDATION inline crypto_word_t constant_time_declassify_w(crypto_word_t v) { - // Return |v| through a value barrier to be safe. Valgrind-based constant-time + // Return `v` through a value barrier to be safe. Valgrind-based constant-time // validation is partly to check the compiler has not undone any constant-time - // work. Any place |BORINGSSL_CONSTANT_TIME_VALIDATION| influences + // work. Any place `BORINGSSL_CONSTANT_TIME_VALIDATION` influences // optimizations, this validation is inaccurate. // // However, by sending pointers through valgrind, we likely inhibit escape @@ -518,8 +518,8 @@ return value_barrier_u32(v); } -// declassify_assert behaves like |assert| but declassifies the result of -// evaluating |expr|. This allows the assertion to branch on the (presumably +// declassify_assert behaves like `assert` but declassifies the result of +// evaluating `expr`. This allows the assertion to branch on the (presumably // public) result, but still ensures that values leading up to the computation // were secret. #define declassify_assert(expr) assert(constant_time_declassify_int(expr)) @@ -540,13 +540,13 @@ #error "Unknown threading library" #endif -// CRYPTO_once calls |init| exactly once per process. This is thread-safe: if -// concurrent threads call |CRYPTO_once| with the same |CRYPTO_once_t| argument -// then they will block until |init| completes, but |init| will have only been +// CRYPTO_once calls `init` exactly once per process. This is thread-safe: if +// concurrent threads call `CRYPTO_once` with the same `CRYPTO_once_t` argument +// then they will block until `init` completes, but `init` will have only been // called once. // -// The |once| argument must be a |CRYPTO_once_t| that has been initialised with -// the value |CRYPTO_ONCE_INIT|. +// The `once` argument must be a `CRYPTO_once_t` that has been initialised with +// the value `CRYPTO_ONCE_INIT`. OPENSSL_EXPORT void CRYPTO_once(CRYPTO_once_t *once, void (*init)()); @@ -606,20 +606,20 @@ using CRYPTO_refcount_t = Atomic<uint32_t>; -// CRYPTO_refcount_inc atomically increments the value at |*count| unless the +// CRYPTO_refcount_inc atomically increments the value at `*count` unless the // value would overflow. It's safe for multiple threads to concurrently call -// this or |CRYPTO_refcount_dec_and_test_zero| on the same -// |CRYPTO_refcount_t|. +// this or `CRYPTO_refcount_dec_and_test_zero` on the same +// `CRYPTO_refcount_t`. OPENSSL_EXPORT void CRYPTO_refcount_inc(CRYPTO_refcount_t *count); -// CRYPTO_refcount_dec_and_test_zero tests the value at |*count|: +// CRYPTO_refcount_dec_and_test_zero tests the value at `*count`: // if it's zero, it crashes the address space. // if it's the maximum value, it returns zero. // otherwise, it atomically decrements it and returns one iff the resulting // value is zero. // // It's safe for multiple threads to concurrently call this or -// |CRYPTO_refcount_inc| on the same |CRYPTO_refcount_t|. +// `CRYPTO_refcount_inc` on the same `CRYPTO_refcount_t`. OPENSSL_EXPORT int CRYPTO_refcount_dec_and_test_zero(CRYPTO_refcount_t *count); @@ -718,18 +718,18 @@ // CRYPTO_set_thread_local sets a pointer value for the current thread at the // given index. This function should only be called once per thread for a given -// |index|: rather than update the pointer value itself, update the data that +// `index`: rather than update the pointer value itself, update the data that // is pointed to. // // The destructor function will be called when a thread exits to free this -// thread-local data. All calls to |CRYPTO_set_thread_local| with the same -// |index| should have the same |destructor| argument. The destructor may be +// thread-local data. All calls to `CRYPTO_set_thread_local` with the same +// `index` should have the same `destructor` argument. The destructor may be // called with a NULL argument if a thread that never set a thread-local -// pointer for |index|, exits. The destructor may be called concurrently with +// pointer for `index`, exits. The destructor may be called concurrently with // different arguments. // // This function returns one on success or zero on error. If it returns zero -// then |destructor| has been called with |value| already. +// then `destructor` has been called with `value` already. OPENSSL_EXPORT int CRYPTO_set_thread_local( thread_local_data_t index, void *value, thread_local_destructor_t destructor); @@ -755,20 +755,20 @@ : num_reserved(with_app_data ? 1 : 0) {} StaticMutex lock; - // funcs is a linked list of |ExDataFuncs| structures. It may be traversed - // without serialization only up to |num_funcs|. last points to the final - // entry of |funcs|, or nullptr if empty. + // funcs is a linked list of `ExDataFuncs` structures. It may be traversed + // without serialization only up to `num_funcs`. last points to the final + // entry of `funcs`, or nullptr if empty. ExDataFuncs *funcs = nullptr, *last = nullptr; - // num_funcs is the number of entries in |funcs|. + // num_funcs is the number of entries in `funcs`. Atomic<uint32_t> num_funcs = 0; // num_reserved is one if the ex_data index zero is reserved for legacy - // |TYPE_get_app_data| functions. + // `TYPE_get_app_data` functions. uint8_t num_reserved = 0; }; -// CRYPTO_get_ex_new_index_ex allocates a new index for |ex_data_class|. Each +// CRYPTO_get_ex_new_index_ex allocates a new index for `ex_data_class`. Each // class of object should provide a wrapper function that uses the correct -// |ExDataClass|. It returns the new index on success and -1 on error. +// `ExDataClass`. It returns the new index on success and -1 on error. OPENSSL_EXPORT int CRYPTO_get_ex_new_index_ex( ExDataClass *ex_data_class, long argl, void *argp, CRYPTO_EX_free *free_func); @@ -782,10 +782,10 @@ // function. OPENSSL_EXPORT void *CRYPTO_get_ex_data(const CRYPTO_EX_DATA *ad, int index); -// CRYPTO_new_ex_data initialises a newly allocated |CRYPTO_EX_DATA|. +// CRYPTO_new_ex_data initialises a newly allocated `CRYPTO_EX_DATA`. OPENSSL_EXPORT void CRYPTO_new_ex_data(CRYPTO_EX_DATA *ad); -// CRYPTO_free_ex_data frees |ad|, which is an object of the given class. +// CRYPTO_free_ex_data frees `ad`, which is an object of the given class. OPENSSL_EXPORT void CRYPTO_free_ex_data(ExDataClass *ex_data_class, CRYPTO_EX_DATA *ad); @@ -831,9 +831,9 @@ // These wrapper functions behave the same as the corresponding C standard // functions, but behave as expected when passed NULL if the length is zero. // -// Note |OPENSSL_memcmp| is a different function from |CRYPTO_memcmp|. +// Note `OPENSSL_memcmp` is a different function from `CRYPTO_memcmp`. -// C++ defines |memchr| as a const-correct overload. +// C++ defines `memchr` as a const-correct overload. inline const void *OPENSSL_memchr(const void *s, int c, size_t n) { if (n == 0) { return nullptr; @@ -886,7 +886,7 @@ // Loads and stores. // // The following functions load and store sized integers with the specified -// endianness. They use |memcpy|, and so avoid alignment or strict aliasing +// endianness. They use `memcpy`, and so avoid alignment or strict aliasing // requirements on the input and output pointers. inline uint16_t CRYPTO_load_u16_le(const void *in) { @@ -977,7 +977,7 @@ // Bit rotation functions. // -// Note these functions use |(-shift) & 31|, etc., because shifting by the bit +// Note these functions use `(-shift) & 31`, etc., because shifting by the bit // width is undefined. Both Clang and GCC recognize this pattern as a rotation, // but MSVC does not. Instead, we call MSVC's built-in functions. @@ -1025,7 +1025,7 @@ // boringssl_self_test_startup runs all startup self tests and returns one on // success or zero on error. Startup self tests do not include lazy tests. -// Call |BORINGSSL_self_test| to run every self test. +// Call `BORINGSSL_self_test` to run every self test. int boringssl_self_test_startup(); // boringssl_ensure_rsa_sign_self_test checks whether the RSA signing self-test @@ -1059,7 +1059,7 @@ #endif // FIPS -// BORINGSSL_check_test checks that |expected| and |actual| are equal. It +// BORINGSSL_check_test checks that `expected` and `actual` are equal. It // returns 1 on success and, on failure, it prints an error message that // includes the hexdumps the two values and returns 0. int BORINGSSL_check_test(Span<const uint8_t> expected, @@ -1121,16 +1121,16 @@ // and AVX512 bits in XCR0, so it is not necessary to check those. (WARNING: See // caveats in cpu_intel.c.) // -// This symbol should only be accessed with |OPENSSL_get_ia32cap|. +// This symbol should only be accessed with `OPENSSL_get_ia32cap`. extern uint32_t OPENSSL_ia32cap_P[4]; -// OPENSSL_get_ia32cap initializes the library if needed and returns the |idx|th -// entry of |OPENSSL_ia32cap_P|. It is marked as a const function so duplicate +// OPENSSL_get_ia32cap initializes the library if needed and returns the `idx`th +// entry of `OPENSSL_ia32cap_P`. It is marked as a const function so duplicate // calls can be merged by the compiler, at least when indices match. OPENSSL_ATTR_CONST uint32_t OPENSSL_get_ia32cap(int idx); -// OPENSSL_adjust_ia32cap adjusts |cap|, which should contain -// |OPENSSL_ia32cap_P|, based on the environment variable value in |env|. This +// OPENSSL_adjust_ia32cap adjusts `cap`, which should contain +// `OPENSSL_ia32cap_P`, based on the environment variable value in `env`. This // function is exposed for unit tests. void OPENSSL_adjust_ia32cap(uint32_t cap[4], const char *env); @@ -1183,8 +1183,8 @@ #endif } -// We intentionally avoid defining a |CRYPTO_is_XSAVE_capable| function. See -// |CRYPTO_cpu_perf_is_like_silvermont|. +// We intentionally avoid defining a `CRYPTO_is_XSAVE_capable` function. See +// `CRYPTO_cpu_perf_is_like_silvermont`. inline int CRYPTO_is_AVX_capable() { #if defined(__AVX__) @@ -1195,7 +1195,7 @@ } inline int CRYPTO_is_RDRAND_capable() { - // We intentionally do not check |__RDRND__| here. On some AMD processors, we + // We intentionally do not check `__RDRND__` here. On some AMD processors, we // will act as if the hardware is RDRAND-incapable, even it actually supports // it. See cpu_intel.c. return (OPENSSL_get_ia32cap(1) & (1u << 30)) != 0; @@ -1334,11 +1334,11 @@ #define ARMV8_SHA3 (1 << 7) #if defined(OPENSSL_STATIC_ARMCAP) -// We assume |CRYPTO_is_*_capable| already checked static capabilities. +// We assume `CRYPTO_is_*_capable` already checked static capabilities. inline uint32_t OPENSSL_get_armcap() { return 0; } #else // OPENSSL_armcap_P contains ARM CPU capabilities as a bitmask of the above -// constants. This should only be accessed with |OPENSSL_get_armcap|. +// constants. This should only be accessed with `OPENSSL_get_armcap`. extern uint32_t OPENSSL_armcap_P; // OPENSSL_get_armcap initializes the library if needed and returns ARM CPU @@ -1389,7 +1389,7 @@ } inline int CRYPTO_is_ARMv8_SHA1_capable() { - // SHA-1 and SHA-2 (only) share |__ARM_FEATURE_SHA2| but otherwise + // SHA-1 and SHA-2 (only) share `__ARM_FEATURE_SHA2` but otherwise // are dealt with independently. #if defined(OPENSSL_STATIC_ARMCAP_SHA1) || defined(__ARM_FEATURE_SHA2) return 1; @@ -1399,7 +1399,7 @@ } inline int CRYPTO_is_ARMv8_SHA256_capable() { - // SHA-1 and SHA-2 (only) share |__ARM_FEATURE_SHA2| but otherwise + // SHA-1 and SHA-2 (only) share `__ARM_FEATURE_SHA2` but otherwise // are dealt with independently. #if defined(OPENSSL_STATIC_ARMCAP_SHA256) || defined(__ARM_FEATURE_SHA2) return 1; @@ -1409,7 +1409,7 @@ } inline int CRYPTO_is_ARMv8_SHA512_capable() { - // There is no |OPENSSL_STATIC_ARMCAP_SHA512|. + // There is no `OPENSSL_STATIC_ARMCAP_SHA512`. #if defined(__ARM_FEATURE_SHA512) return 1; #else @@ -1418,7 +1418,7 @@ } inline int CRYPTO_is_ARMv8_SHA3_capable() { - // There is no |OPENSSL_STATIC_ARMCAP_SHA3|. + // There is no `OPENSSL_STATIC_ARMCAP_SHA3`. #if defined(__ARM_FEATURE_SHA3) return 1; #else @@ -1446,10 +1446,10 @@ #endif // BORINGSSL_DISPATCH_TEST -// OPENSSL_vasprintf_internal is just like |vasprintf(3)|. If |system_malloc| is -// 0, memory will be allocated with |OPENSSL_malloc| and must be freed with -// |OPENSSL_free|. Otherwise the system |malloc| function is used and the memory -// must be freed with the system |free| function. +// OPENSSL_vasprintf_internal is just like `vasprintf(3)`. If `system_malloc` is +// 0, memory will be allocated with `OPENSSL_malloc` and must be freed with +// `OPENSSL_free`. Otherwise the system `malloc` function is used and the memory +// must be freed with the system `free` function. OPENSSL_EXPORT int OPENSSL_vasprintf_internal(char **str, const char *format, va_list args, int system_malloc) OPENSSL_PRINTF_FORMAT_FUNC(2, 0); @@ -1459,7 +1459,7 @@ #if defined(FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION) // CRYPTO_fuzzer_mode_enabled returns whether fuzzer mode is enabled. See -// |CRYPTO_set_fuzzer_mode|. In non-fuzzer builds, this function statically +// `CRYPTO_set_fuzzer_mode`. In non-fuzzer builds, this function statically // returns zero so the codepaths will be deleted by the optimizer. int CRYPTO_fuzzer_mode_enabled(); #else @@ -1469,8 +1469,8 @@ // Arithmetic functions. -// CRYPTO_addc_* returns |x + y + carry|, and sets |*out_carry| to the carry -// bit. |carry| must be zero or one. +// CRYPTO_addc_* returns `x + y + carry`, and sets `*out_carry` to the carry +// bit. `carry` must be zero or one. // NOTE: Unoptimized GCC builds may compile these builtins to non-constant-time // code. For correct constant-time behavior, ensure builds are optimized. @@ -1546,8 +1546,8 @@ #endif -// CRYPTO_subc_* returns |x - y - borrow|, and sets |*out_borrow| to the borrow -// bit. |borrow| must be zero or one. +// CRYPTO_subc_* returns `x - y - borrow`, and sets `*out_borrow` to the borrow +// bit. `borrow` must be zero or one. #if OPENSSL_HAS_BUILTIN(__builtin_subc) inline unsigned int CRYPTO_subc_impl(unsigned int x, unsigned int y, @@ -1640,13 +1640,13 @@ template <typename F> Cleanup(F func) -> Cleanup<F>; -// DECLARE_OPAQUE_STRUCT defines a public struct |public_name| with an -// implementation struct |impl_name|. +// DECLARE_OPAQUE_STRUCT defines a public struct `public_name` with an +// implementation struct `impl_name`. // -// To prevent accidents, the |public_name| struct will be neither constructable, +// To prevent accidents, the `public_name` struct will be neither constructable, // nor copyable/movable, nor deletable. // -// It must be used from inside the |bssl| namespace; however, |public_name| will +// It must be used from inside the `bssl` namespace; however, `public_name` will // be defined outside. // // Usage: @@ -1666,8 +1666,8 @@ // // The implementation struct can be converted to the public struct implicitly; // to convert the public struct to the implementation struct, call -// |FromOpaque| on it. It is explicitly allowed to call |FromOpaque| on a -// |nullptr|. +// `FromOpaque` on it. It is explicitly allowed to call `FromOpaque` on a +// `nullptr`. #define DECLARE_OPAQUE_STRUCT(public_name, impl_name) \ BSSL_NAMESPACE_BEGIN \ class impl_name; \
diff --git a/crypto/kyber/internal.h b/crypto/kyber/internal.h index 21ec5af..20a5379 100644 --- a/crypto/kyber/internal.h +++ b/crypto/kyber/internal.h
@@ -56,15 +56,15 @@ #define KYBER_SHARED_SECRET_BYTES 32 // KYBER_generate_key generates a random public/private key pair, writes the -// encoded public key to |out_encoded_public_key| and sets |out_private_key| to +// encoded public key to `out_encoded_public_key` and sets `out_private_key` to // the private key. OPENSSL_EXPORT void KYBER_generate_key( uint8_t out_encoded_public_key[KYBER_PUBLIC_KEY_BYTES], struct KYBER_private_key *out_private_key); -// KYBER_public_from_private sets |*out_public_key| to the public key that -// corresponds to |private_key|. (This is faster than parsing the output of -// |KYBER_generate_key| if, for some reason, you need to encapsulate to a key +// KYBER_public_from_private sets `*out_public_key` to the public key that +// corresponds to `private_key`. (This is faster than parsing the output of +// `KYBER_generate_key` if, for some reason, you need to encapsulate to a key // that was just generated.) OPENSSL_EXPORT void KYBER_public_from_private( struct KYBER_public_key *out_public_key, @@ -73,20 +73,20 @@ // KYBER_CIPHERTEXT_BYTES is number of bytes in the Kyber768 ciphertext. #define KYBER_CIPHERTEXT_BYTES 1088 -// KYBER_encap encrypts a random shared secret for |public_key|, writes the -// ciphertext to |out_ciphertext|, and writes the random shared secret to -// |out_shared_secret|. +// KYBER_encap encrypts a random shared secret for `public_key`, writes the +// ciphertext to `out_ciphertext`, and writes the random shared secret to +// `out_shared_secret`. OPENSSL_EXPORT void KYBER_encap( uint8_t out_ciphertext[KYBER_CIPHERTEXT_BYTES], uint8_t out_shared_secret[KYBER_SHARED_SECRET_BYTES], const struct KYBER_public_key *public_key); -// KYBER_decap decrypts a shared secret from |ciphertext| using |private_key| -// and writes it to |out_shared_secret|. If |ciphertext| is invalid, -// |out_shared_secret| is filled with a key that will always be the same for the -// same |ciphertext| and |private_key|, but which appears to be random unless -// one has access to |private_key|. These alternatives occur in constant time. -// Any subsequent symmetric encryption using |out_shared_secret| must use an +// KYBER_decap decrypts a shared secret from `ciphertext` using `private_key` +// and writes it to `out_shared_secret`. If `ciphertext` is invalid, +// `out_shared_secret` is filled with a key that will always be the same for the +// same `ciphertext` and `private_key`, but which appears to be random unless +// one has access to `private_key`. These alternatives occur in constant time. +// Any subsequent symmetric encryption using `out_shared_secret` must use an // authenticated encryption scheme in order to discover the decapsulation // failure. OPENSSL_EXPORT void KYBER_decap( @@ -97,33 +97,33 @@ // Serialisation of keys. -// KYBER_marshal_public_key serializes |public_key| to |out| in the standard +// KYBER_marshal_public_key serializes `public_key` to `out` in the standard // format for Kyber public keys. It returns one on success or zero on allocation // error. OPENSSL_EXPORT int KYBER_marshal_public_key( CBB *out, const struct KYBER_public_key *public_key); // KYBER_parse_public_key parses a public key, in the format generated by -// |KYBER_marshal_public_key|, from |in| and writes the result to -// |out_public_key|. It returns one on success or zero on parse error or if -// there are trailing bytes in |in|. +// `KYBER_marshal_public_key`, from `in` and writes the result to +// `out_public_key`. It returns one on success or zero on parse error or if +// there are trailing bytes in `in`. OPENSSL_EXPORT int KYBER_parse_public_key( struct KYBER_public_key *out_public_key, CBS *in); -// KYBER_marshal_private_key serializes |private_key| to |out| in the standard +// KYBER_marshal_private_key serializes `private_key` to `out` in the standard // format for Kyber private keys. It returns one on success or zero on // allocation error. OPENSSL_EXPORT int KYBER_marshal_private_key( CBB *out, const struct KYBER_private_key *private_key); // KYBER_PRIVATE_KEY_BYTES is the length of the data produced by -// |KYBER_marshal_private_key|. +// `KYBER_marshal_private_key`. #define KYBER_PRIVATE_KEY_BYTES 2400 // KYBER_parse_private_key parses a private key, in the format generated by -// |KYBER_marshal_private_key|, from |in| and writes the result to -// |out_private_key|. It returns one on success or zero on parse error or if -// there are trailing bytes in |in|. +// `KYBER_marshal_private_key`, from `in` and writes the result to +// `out_private_key`. It returns one on success or zero on parse error or if +// there are trailing bytes in `in`. OPENSSL_EXPORT int KYBER_parse_private_key( struct KYBER_private_key *out_private_key, CBS *in); @@ -142,18 +142,18 @@ // KYBER_generate_key_external_entropy is a deterministic function to create a // pair of Kyber768 keys, using the supplied entropy. The entropy needs to be // uniformly random generated. This function is should only be used for tests, -// regular callers should use the non-deterministic |KYBER_generate_key| +// regular callers should use the non-deterministic `KYBER_generate_key` // directly. OPENSSL_EXPORT void KYBER_generate_key_external_entropy( uint8_t out_encoded_public_key[KYBER_PUBLIC_KEY_BYTES], struct KYBER_private_key *out_private_key, const uint8_t entropy[KYBER_GENERATE_KEY_ENTROPY]); -// KYBER_encap_external_entropy behaves like |KYBER_encap|, but uses -// |KYBER_ENCAP_ENTROPY| bytes of |entropy| for randomization. The decapsulating -// side will be able to recover |entropy| in full. This function should only be +// KYBER_encap_external_entropy behaves like `KYBER_encap`, but uses +// `KYBER_ENCAP_ENTROPY` bytes of `entropy` for randomization. The decapsulating +// side will be able to recover `entropy` in full. This function should only be // used for tests, regular callers should use the non-deterministic -// |KYBER_encap| directly. +// `KYBER_encap` directly. OPENSSL_EXPORT void KYBER_encap_external_entropy( uint8_t out_ciphertext[KYBER_CIPHERTEXT_BYTES], uint8_t out_shared_secret[KYBER_SHARED_SECRET_BYTES],
diff --git a/crypto/lhash/internal.h b/crypto/lhash/internal.h index 27c7780..6b5e0f8 100644 --- a/crypto/lhash/internal.h +++ b/crypto/lhash/internal.h
@@ -24,8 +24,8 @@ // contracts as needed. One should not use the lh_* functions directly, rather // use the type-safe macro wrappers: // -// A hash table of a specific type of object has type |LHASH_OF(type)|. This -// can be defined (once) with |DEFINE_LHASH_OF(type)|. +// A hash table of a specific type of object has type `LHASH_OF(type)`. This +// can be defined (once) with `DEFINE_LHASH_OF(type)`. // // struct foo { // int bar; @@ -33,10 +33,10 @@ // // DEFINE_LHASH_OF(struct foo) // -// Although note that the hash table will contain /pointers/ to |foo|. +// Although note that the hash table will contain /pointers/ to `foo`. // -// A macro will be defined for each of the |OPENSSL_lh_*| functions below. For -// |LHASH_OF(foo)|, the macros would be |lh_foo_new|, |lh_foo_num_items| etc. +// A macro will be defined for each of the `OPENSSL_lh_*` functions below. For +// `LHASH_OF(foo)`, the macros would be `lh_foo_new`, `lh_foo_num_items` etc. // // TODO(davidben): Now that this type is completely internal, this can just be a // C++ template without any macros. @@ -45,12 +45,12 @@ #define LHASH_OF(type) struct bssl::type##_lhash_st // lhash_cmp_func is a comparison function that returns a value equal, or not -// equal, to zero depending on whether |*a| is equal, or not equal to |*b|, -// respectively. Note the difference between this and |stack_cmp_func| in that +// equal, to zero depending on whether `*a` is equal, or not equal to `*b`, +// respectively. Note the difference between this and `stack_cmp_func` in that // this takes pointers to the objects directly. // // This function's actual type signature is int (*)(const T*, const T*). The -// low-level |lh_*| functions will be passed a type-specific wrapper to call it +// low-level `lh_*` functions will be passed a type-specific wrapper to call it // correctly. typedef int (*lhash_cmp_func)(const void *a, const void *b); typedef int (*lhash_cmp_func_helper)(lhash_cmp_func func, const void *a, @@ -60,7 +60,7 @@ // uint32_t. // // This function's actual type signature is uint32_t (*)(const T*). The -// low-level |lh_*| functions will be passed a type-specific wrapper to call it +// low-level `lh_*` functions will be passed a type-specific wrapper to call it // correctly. typedef uint32_t (*lhash_hash_func)(const void *a); typedef uint32_t (*lhash_hash_func_helper)(lhash_hash_func func, const void *a); @@ -72,45 +72,45 @@ lhash_cmp_func comp); // OPENSSL_lh_free frees the hash table itself but none of the elements. See -// |OPENSSL_lh_doall|. +// `OPENSSL_lh_doall`. OPENSSL_EXPORT void OPENSSL_lh_free(_LHASH *lh); -// OPENSSL_lh_num_items returns the number of items in |lh|. +// OPENSSL_lh_num_items returns the number of items in `lh`. OPENSSL_EXPORT size_t OPENSSL_lh_num_items(const _LHASH *lh); -// OPENSSL_lh_retrieve finds an element equal to |data| in the hash table and +// OPENSSL_lh_retrieve finds an element equal to `data` in the hash table and // returns it. If no such element exists, it returns NULL. OPENSSL_EXPORT void *OPENSSL_lh_retrieve(const _LHASH *lh, const void *data, lhash_hash_func_helper call_hash_func, lhash_cmp_func_helper call_cmp_func); -// OPENSSL_lh_retrieve_key finds an element matching |key|, given the specified -// hash and comparison function. This differs from |OPENSSL_lh_retrieve| in that -// the key may be a different type than the values stored in |lh|. |key_hash| -// and |cmp_key| must be compatible with the functions passed into -// |OPENSSL_lh_new|. +// OPENSSL_lh_retrieve_key finds an element matching `key`, given the specified +// hash and comparison function. This differs from `OPENSSL_lh_retrieve` in that +// the key may be a different type than the values stored in `lh`. `key_hash` +// and `cmp_key` must be compatible with the functions passed into +// `OPENSSL_lh_new`. OPENSSL_EXPORT void *OPENSSL_lh_retrieve_key(const _LHASH *lh, const void *key, uint32_t key_hash, int (*cmp_key)(const void *key, const void *value)); -// OPENSSL_lh_insert inserts |data| into the hash table. If an existing element -// is equal to |data| (with respect to the comparison function) then |*old_data| +// OPENSSL_lh_insert inserts `data` into the hash table. If an existing element +// is equal to `data` (with respect to the comparison function) then `*old_data` // will be set to that value and it will be replaced. Otherwise, or in the -// event of an error, |*old_data| will be set to NULL. It returns one on +// event of an error, `*old_data` will be set to NULL. It returns one on // success or zero in the case of an allocation error. OPENSSL_EXPORT int OPENSSL_lh_insert(_LHASH *lh, void **old_data, void *data, lhash_hash_func_helper call_hash_func, lhash_cmp_func_helper call_cmp_func); -// OPENSSL_lh_delete removes an element equal to |data| from the hash table and +// OPENSSL_lh_delete removes an element equal to `data` from the hash table and // returns it. If no such element is found, it returns NULL. OPENSSL_EXPORT void *OPENSSL_lh_delete(_LHASH *lh, const void *data, lhash_hash_func_helper call_hash_func, lhash_cmp_func_helper call_cmp_func); -// OPENSSL_lh_doall_arg calls |func| on each element of the hash table and also -// passes |arg| as the second argument. +// OPENSSL_lh_doall_arg calls `func` on each element of the hash table and also +// passes `arg` as the second argument. // TODO(fork): rename this OPENSSL_EXPORT void OPENSSL_lh_doall_arg(_LHASH *lh, void (*func)(void *, void *), @@ -122,9 +122,9 @@ /* We disable MSVC C4191 in this macro, which warns when pointers are cast \ * to the wrong type. While the cast itself is valid, it is often a bug \ * because calling it through the cast is UB. However, we never actually \ - * call functions as |lhash_cmp_func|. The type is just a type-erased \ + * call functions as `lhash_cmp_func`. The type is just a type-erased \ * function pointer. (C does not guarantee function pointers fit in \ - * |void*|, and GCC will warn on this.) Thus we just disable the false \ + * `void*`, and GCC will warn on this.) Thus we just disable the false \ * positive warning. */ \ OPENSSL_MSVC_PRAGMA(warning(push)) \ OPENSSL_MSVC_PRAGMA(warning(disable : 4191)) \
diff --git a/crypto/mem_internal.h b/crypto/mem_internal.h index 78c3348..7b28cca 100644 --- a/crypto/mem_internal.h +++ b/crypto/mem_internal.h
@@ -33,24 +33,24 @@ // Internal allocation-dependent functions. // // This header is separate from crypto/internal.h because there are some files -// which must avoid |OPENSSL_malloc|, to avoid a circular dependency, but +// which must avoid `OPENSSL_malloc`, to avoid a circular dependency, but // need other support routines in crypto/internal.h. (See -// |_BORINGSSL_PROHIBIT_OPENSSL_MALLOC|.) +// `_BORINGSSL_PROHIBIT_OPENSSL_MALLOC`.) // Memory allocation. -// New behaves like |new| but uses |OPENSSL_malloc| for memory allocation. It +// New behaves like `new` but uses `OPENSSL_malloc` for memory allocation. It // returns nullptr on allocation error. It only implements single-object // allocation and not new T[n]. // // When called with no arguments, it performs value-initialization, not // default-initialization. This means that, if selects a non-user-provided // constructor, the object will be zero-initialized. (As in any C++ type, once -// |T| gains a user-provided constructors, it is responsible for initializing +// `T` gains a user-provided constructors, it is responsible for initializing // all fields explicitly.) // -// Note: unlike |new|, this does not support non-public constructors. +// Note: unlike `new`, this does not support non-public constructors. template <typename T, typename... Args> T *New(Args &&...args) { void *t = OPENSSL_malloc(sizeof(T)); @@ -60,9 +60,9 @@ return new (t) T(std::forward<Args>(args)...); } -// Delete behaves like |delete| but uses |OPENSSL_free| to release memory. +// Delete behaves like `delete` but uses `OPENSSL_free` to release memory. // -// Note: unlike |delete| this does not support non-public destructors. +// Note: unlike `delete` this does not support non-public destructors. template <typename T> void Delete(T *t) { if (t != nullptr) { @@ -74,9 +74,9 @@ namespace internal { // All types with kAllowUniquePtr set may be used with UniquePtr. Other types -// may be C structs which require a |BORINGSSL_MAKE_DELETER| registration. Where +// may be C structs which require a `BORINGSSL_MAKE_DELETER` registration. Where // an internal type cannot be annotated (e.g. an alias of std::variant), use -// |BORINGSSL_MAKE_DELETER(T, Delete)|. +// `BORINGSSL_MAKE_DELETER(T, Delete)`. template <typename T> struct DeleterImpl<T, std::enable_if_t<T::kAllowUniquePtr>> { static void Free(T *t) { Delete(t); } @@ -93,7 +93,7 @@ // All types with kAllowRefCountedUniquePtr types also automatically get an // UpRef function. Other types may be C structs which require a -// |BORINGSSL_MAKE_UP_REF| registration. +// `BORINGSSL_MAKE_UP_REF` registration. template <typename T, typename = std::enable_if_t<T::kAllowRefCountedUniquePtr>> inline UniquePtr<T> UpRef(const T *v) { if (v != nullptr) { @@ -106,7 +106,7 @@ return UpRef(ptr.get()); } -// MakeUnique behaves like |std::make_unique| but returns nullptr on allocation +// MakeUnique behaves like `std::make_unique` but returns nullptr on allocation // error. template <typename T, typename... Args> UniquePtr<T> MakeUnique(Args &&...args) { @@ -128,7 +128,7 @@ // These methods are intentionally named differently from `bssl::UpRef` to // avoid a collision. Only the implementations of `FOO_up_ref` and `FOO_free` - // should call these. |DecRefInternal| returns true if the object was freed + // should call these. `DecRefInternal` returns true if the object was freed // and false if there are still references. void UpRefInternal() const { // Safety: the folowing call does not mutate anything other than the atomic @@ -168,7 +168,7 @@ // Containers. -// Array<T> is an owning array of elements of |T|. +// Array<T> is an owning array of elements of `T`. template <typename T> class Array { public: @@ -244,9 +244,9 @@ size_ = 0; } - // Init replaces the array with a newly-allocated array of |new_size| - // value-constructed copies of |T|. It returns true on success and false on - // error. If |T| is a primitive type like |uint8_t|, value-construction means + // Init replaces the array with a newly-allocated array of `new_size` + // value-constructed copies of `T`. It returns true on success and false on + // error. If `T` is a primitive type like `uint8_t`, value-construction means // it will be zero-initialized. [[nodiscard]] bool Init(size_t new_size) { if (!InitUninitialized(new_size)) { @@ -256,8 +256,8 @@ return true; } - // InitForOverwrite behaves like |Init| but it default-constructs each element - // instead. This means that, if |T| is a primitive type, the array will be + // InitForOverwrite behaves like `Init` but it default-constructs each element + // instead. This means that, if `T` is a primitive type, the array will be // uninitialized and thus must be filled in by the caller. [[nodiscard]] bool InitForOverwrite(size_t new_size) { if (!InitUninitialized(new_size)) { @@ -267,10 +267,10 @@ return true; } - // CopyFrom replaces the array with a newly-allocated copy of |in|. It returns + // CopyFrom replaces the array with a newly-allocated copy of `in`. It returns // true on success and false on error. // - // |in| may not alias |this|. + // `in` may not alias `this`. [[nodiscard]] bool CopyFrom(Span<const T> in) { BSSL_CHECK(!spans_alias(MakeConstSpan(*this), in)); if (!InitUninitialized(in.size())) { @@ -280,7 +280,7 @@ return true; } - // Shrink shrinks the stored size of the array to |new_size|. It crashes if + // Shrink shrinks the stored size of the array to `new_size`. It crashes if // the new size is larger. Note this does not shrink the allocation itself. void Shrink(size_t new_size) { if (new_size > size_) { @@ -292,7 +292,7 @@ private: // InitUninitialized replaces the array with a newly-allocated array of - // |new_size| elements, but whose constructor has not yet run. On success, the + // `new_size` elements, but whose constructor has not yet run. On success, the // elements must be constructed before returning control to the caller. bool InitUninitialized(size_t new_size) { Reset(); @@ -316,7 +316,7 @@ size_t size_ = 0; }; -// Vector<T> is a resizable array of elements of |T|. +// Vector<T> is a resizable array of elements of `T`. template <typename T> class Vector { public: @@ -384,7 +384,7 @@ size_--; } - // Push adds |elem| at the end of the internal array, growing if necessary. It + // Push adds `elem` at the end of the internal array, growing if necessary. It // returns false when allocation fails. [[nodiscard]] bool Push(T elem) { if (!MaybeGrow(1)) { @@ -395,7 +395,7 @@ return true; } - // CopyFrom replaces the contents of the array with a copy of |in|. It returns + // CopyFrom replaces the contents of the array with a copy of `in`. It returns // true on success and false on allocation error. [[nodiscard]] bool CopyFrom(Span<const T> in) { Array<T> copy; @@ -409,7 +409,7 @@ return true; } - // Append appends the contents of |in| to the array. It returns true on + // Append appends the contents of `in` to the array. It returns true on // success and false on allocation error. [[nodiscard]] bool Append(Span<const T> in) { if (!MaybeGrow(in.size())) { @@ -420,7 +420,7 @@ return true; } - // AppendMove moves the contents of |in| and appends them to the array. It + // AppendMove moves the contents of `in` and appends them to the array. It // returns true on success and false on allocation error. [[nodiscard]] bool AppendMove(Span<T> in) { if (!MaybeGrow(in.size())) { @@ -431,7 +431,7 @@ return true; } - // EraseIf removes all elements that satisfy the predicate |pred|. + // EraseIf removes all elements that satisfy the predicate `pred`. template <typename Pred> void EraseIf(Pred pred) { auto it = std::remove_if(begin(), end(), pred); @@ -440,7 +440,7 @@ } private: - // If there is no room for |num| elements, creates a new backing array with + // If there is no room for `num` elements, creates a new backing array with // double the size of the old one and copies elements over. [[nodiscard]] bool MaybeGrow(size_t num) { constexpr size_t kDefaultSize = 16; @@ -475,12 +475,12 @@ return true; } - // data_ is a pointer to |capacity_| objects of size |T|, the first |size_| of + // data_ is a pointer to `capacity_` objects of size `T`, the first `size_` of // which are constructed. T *data_ = nullptr; - // |size_| is the number of elements stored in this Vector. + // `size_` is the number of elements stored in this Vector. size_t size_ = 0; - // |capacity_| is the number of elements allocated in this Vector. + // `capacity_` is the number of elements allocated in this Vector. size_t capacity_ = 0; }; @@ -560,8 +560,8 @@ Shrink(size_ - 1); } - // Shrink resizes the vector to |new_size|, which must not be larger than the - // current size. Unlike |Resize|, this can be called when |T| is not + // Shrink resizes the vector to `new_size`, which must not be larger than the + // current size. Unlike `Resize`, this can be called when `T` is not // default-constructible. void Shrink(size_t new_size) { BSSL_CHECK(new_size <= size_); @@ -569,8 +569,8 @@ size_ = static_cast<PackedSize<N>>(new_size); } - // TryResize resizes the vector to |new_size| and returns true, or returns - // false if |new_size| is too large. Any newly-added elements are + // TryResize resizes the vector to `new_size` and returns true, or returns + // false if `new_size` is too large. Any newly-added elements are // value-initialized. [[nodiscard]] bool TryResize(size_t new_size) { if (new_size <= size_) { @@ -585,7 +585,7 @@ return true; } - // TryResizeForOverwrite behaves like |TryResize|, but newly-added elements + // TryResizeForOverwrite behaves like `TryResize`, but newly-added elements // are default-initialized, so POD types may contain uninitialized values that // the caller is responsible for filling in. [[nodiscard]] bool TryResizeForOverwrite(size_t new_size) { @@ -601,10 +601,10 @@ return true; } - // TryCopyFrom sets the vector to a copy of |in| and returns true, or returns - // false if |in| is too large. + // TryCopyFrom sets the vector to a copy of `in` and returns true, or returns + // false if `in` is too large. // - // |in| may not alias |this|. + // `in` may not alias `this`. [[nodiscard]] bool TryCopyFrom(Span<const T> in) { BSSL_CHECK(!spans_alias(MakeConstSpan(*this), in)); if (in.size() > capacity()) { @@ -616,8 +616,8 @@ return true; } - // TryAppend appends the vector by a copy of |in| and returns true, or - // returns false if |in| is too large. + // TryAppend appends the vector by a copy of `in` and returns true, or + // returns false if `in` is too large. [[nodiscard]] bool TryAppend(Span<const T> in) { if (in.size() > capacity() - size()) { return false; @@ -627,7 +627,7 @@ return true; } - // TryPushBack appends |val| to the vector and returns a pointer to the + // TryPushBack appends `val` to the vector and returns a pointer to the // newly-inserted value, or nullptr if the vector is at capacity. [[nodiscard]] T *TryPushBack(T val) { if (size() >= capacity()) { @@ -639,7 +639,7 @@ return ret; } - // The following methods behave like their |Try*| counterparts, but abort the + // The following methods behave like their `Try*` counterparts, but abort the // program on failure. void Resize(size_t size) { BSSL_CHECK(TryResize(size)); } void ResizeForOverwrite(size_t size) { @@ -653,7 +653,7 @@ return *ret; } - // EraseIf removes all elements that satisfy the predicate |pred|. + // EraseIf removes all elements that satisfy the predicate `pred`. template <typename Pred> void EraseIf(Pred pred) { auto it = std::remove_if(begin(), end(), pred);
diff --git a/crypto/pem/internal.h b/crypto/pem/internal.h index 656dffb..ac1c938 100644 --- a/crypto/pem/internal.h +++ b/crypto/pem/internal.h
@@ -23,21 +23,21 @@ BSSL_NAMESPACE_BEGIN -// PEM_get_EVP_CIPHER_INFO decodes |header| as a PEM header block and writes the -// specified cipher and IV to |cipher|. It returns one on success and zero on -// error. |header| must be a NUL-terminated string. If |header| does not +// PEM_get_EVP_CIPHER_INFO decodes `header` as a PEM header block and writes the +// specified cipher and IV to `cipher`. It returns one on success and zero on +// error. `header` must be a NUL-terminated string. If `header` does not // specify encryption, this function will return success and set -// |cipher->cipher| to NULL. +// `cipher->cipher` to NULL. int PEM_get_EVP_CIPHER_INFO(const char *header, EVP_CIPHER_INFO *cipher); -// PEM_do_header decrypts |*len| bytes from |data| in-place according to the -// information in |cipher|. On success, it returns one and sets |*len| to the -// length of the plaintext. Otherwise, it returns zero. If |cipher| specifies -// encryption, the key is derived from a password returned from |callback|. +// PEM_do_header decrypts `*len` bytes from `data` in-place according to the +// information in `cipher`. On success, it returns one and sets `*len` to the +// length of the plaintext. Otherwise, it returns zero. If `cipher` specifies +// encryption, the key is derived from a password returned from `callback`. int PEM_do_header(const EVP_CIPHER_INFO *cipher, uint8_t *data, size_t *len, pem_password_cb *callback, void *u); -// PEM_read_bio_inner differs from |PEM_read_bio| on the out pointer |len| +// PEM_read_bio_inner differs from `PEM_read_bio` on the out pointer `len` // so that it guarantee non-negativeness on this output and it takes in // owned types. int PEM_read_bio_inner(BIO *bp, bssl::UniquePtr<char> *name,
diff --git a/crypto/pkcs7/internal.h b/crypto/pkcs7/internal.h index b85f2be..a6ab04e 100644 --- a/crypto/pkcs7/internal.h +++ b/crypto/pkcs7/internal.h
@@ -21,16 +21,16 @@ BSSL_NAMESPACE_BEGIN // pkcs7_parse_header reads the non-certificate/non-CRL prefix of a PKCS#7 -// SignedData blob from |cbs| and sets |*out| to point to the rest of the -// input. If the input is in BER format, then |*der_bytes| will be set to a +// SignedData blob from `cbs` and sets `*out` to point to the rest of the +// input. If the input is in BER format, then `*der_bytes` will be set to a // pointer that needs to be freed by the caller once they have finished -// processing |*out| (which will be pointing into |*der_bytes|). +// processing `*out` (which will be pointing into `*der_bytes`). // -// It returns one on success or zero on error. On error, |*der_bytes| is +// It returns one on success or zero on error. On error, `*der_bytes` is // NULL. int pkcs7_parse_header(uint8_t **der_bytes, CBS *out, CBS *cbs); -// pkcs7_add_signed_data writes a PKCS#7, SignedData structure to |out|. While +// pkcs7_add_signed_data writes a PKCS#7, SignedData structure to `out`. While // doing so it makes callbacks to let the caller fill in parts of the structure. // All callbacks are ignored if NULL and return one on success or zero on error. // @@ -38,9 +38,9 @@ // it is always 1. In CMS, it depends on the features used. // digest_algos_cb: may write AlgorithmIdentifiers into the given CBB, which // is a SET of digest algorithms. -// cert_crl_cb: may write the |certificates| or |crls| fields. +// cert_crl_cb: may write the `certificates` or `crls` fields. // (See https://datatracker.ietf.org/doc/html/rfc2315#section-9.1) -// signer_infos_cb: may write the contents of the |signerInfos| field. +// signer_infos_cb: may write the contents of the `signerInfos` field. // (See https://datatracker.ietf.org/doc/html/rfc2315#section-9.1) // // pkcs7_add_signed_data returns one on success or zero on error. @@ -51,9 +51,9 @@ void *arg); // pkcs7_add_external_signature writes a PKCS#7 or CMS SignedData structure to -// |out|, containing an external (i.e. the contents are not included) signature, -// using |sign_cert| and |key| to sign the contents of |data| with |md|. If -// |use_key_id| is true (CMS-only), the SignerInfo specifies the signer with key +// `out`, containing an external (i.e. the contents are not included) signature, +// using `sign_cert` and `key` to sign the contents of `data` with `md`. If +// `use_key_id` is true (CMS-only), the SignerInfo specifies the signer with key // identifier. Otherwise, it uses issuer and serial number (PKCS#7 or CMS v1). // The SignedData will have no embedded certificates and no attributes. //
diff --git a/crypto/pkcs8/internal.h b/crypto/pkcs8/internal.h index 89cdf9c..f45c6b9 100644 --- a/crypto/pkcs8/internal.h +++ b/crypto/pkcs8/internal.h
@@ -28,9 +28,9 @@ BSSL_NAMESPACE_BEGIN -// pkcs8_pbe_decrypt decrypts |in| using the PBE scheme described by -// |algorithm|, which should be a serialized AlgorithmIdentifier structure. On -// success, it sets |*out| to a newly-allocated buffer containing the decrypted +// pkcs8_pbe_decrypt decrypts `in` using the PBE scheme described by +// `algorithm`, which should be a serialized AlgorithmIdentifier structure. On +// success, it sets `*out` to a newly-allocated buffer containing the decrypted // result and returns one. Otherwise, it returns zero. int pkcs8_pbe_decrypt(uint8_t **out, size_t *out_len, CBS *algorithm, const char *pass, size_t pass_len, const uint8_t *in, @@ -41,17 +41,17 @@ #define PKCS12_MAC_ID 3 // pkcs12_key_gen runs the PKCS#12 key derivation function as specified in -// RFC 7292, appendix B. On success, it writes the resulting |out_len| bytes of -// key material to |out| and returns one. Otherwise, it returns zero. |id| -// should be one of the |PKCS12_*_ID| values. +// RFC 7292, appendix B. On success, it writes the resulting `out_len` bytes of +// key material to `out` and returns one. Otherwise, it returns zero. `id` +// should be one of the `PKCS12_*_ID` values. int pkcs12_key_gen(const char *pass, size_t pass_len, const uint8_t *salt, size_t salt_len, uint8_t id, uint32_t iterations, size_t out_len, uint8_t *out, const EVP_MD *md); -// pkcs12_pbe_encrypt_init configures |ctx| for encrypting with a PBES1 scheme +// pkcs12_pbe_encrypt_init configures `ctx` for encrypting with a PBES1 scheme // defined in PKCS#12, or a PBES2 scheme defined in PKCS#5. The algorithm is -// determined as in |PKCS8_encrypt|. It writes the corresponding -// AlgorithmIdentifier to |out|. +// determined as in `PKCS8_encrypt`. It writes the corresponding +// AlgorithmIdentifier to `out`. int pkcs12_pbe_encrypt_init(CBB *out, EVP_CIPHER_CTX *ctx, int alg_nid, const EVP_CIPHER *alg_cipher, uint32_t iterations, const char *pass, size_t pass_len, @@ -63,8 +63,8 @@ uint8_t oid_len; const EVP_CIPHER *(*cipher_func)(); const EVP_MD *(*md_func)(); - // decrypt_init initialize |ctx| for decrypting. The password is specified by - // |pass| and |pass_len|. |param| contains the serialized parameters field of + // decrypt_init initialize `ctx` for decrypting. The password is specified by + // `pass` and `pass_len`. `param` contains the serialized parameters field of // the AlgorithmIdentifier. // // It returns one on success and zero on error. @@ -74,22 +74,22 @@ #define PKCS5_SALT_LEN 16 -// pkcs5_pbe2_nid_to_cipher returns the |EVP_CIPHER| for |nid| if |nid| is +// pkcs5_pbe2_nid_to_cipher returns the `EVP_CIPHER` for `nid` if `nid` is // supported with PKCS#5 PBES2, and nullptr otherwise. const EVP_CIPHER *pkcs5_pbe2_nid_to_cipher(int nid); int PKCS5_pbe2_decrypt_init(const struct pbe_suite *suite, EVP_CIPHER_CTX *ctx, const char *pass, size_t pass_len, CBS *param); -// PKCS5_pbe2_encrypt_init configures |ctx| for encrypting with PKCS #5 PBES2, +// PKCS5_pbe2_encrypt_init configures `ctx` for encrypting with PKCS #5 PBES2, // as defined in RFC 2998, with the specified parameters. It writes the -// corresponding AlgorithmIdentifier to |out|. +// corresponding AlgorithmIdentifier to `out`. int PKCS5_pbe2_encrypt_init(CBB *out, EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher, uint32_t iterations, const char *pass, size_t pass_len, const uint8_t *salt, size_t salt_len); -// pkcs12_iterations_acceptable returns one if |iterations| is a reasonable +// pkcs12_iterations_acceptable returns one if `iterations` is a reasonable // number of PBKDF2 iterations and zero otherwise. int pkcs12_iterations_acceptable(uint64_t iterations);
diff --git a/crypto/pool/internal.h b/crypto/pool/internal.h index 6f8165f..49d9b8f 100644 --- a/crypto/pool/internal.h +++ b/crypto/pool/internal.h
@@ -73,11 +73,11 @@ public: CryptoBufferPool(); - // Hash returns the hash of |data|. + // Hash returns the hash of `data`. uint32_t Hash(Span<const uint8_t> data) const; - // FindBufferLocked looks for a buffer with hash |hash| and contents |data|. - // It returns it if found and nullptr otherwise. |handle_->lock_| must be + // FindBufferLocked looks for a buffer with hash `hash` and contents `data`. + // It returns it if found and nullptr otherwise. `handle_->lock_` must be // locked for reading or writing before calling this. CryptoBuffer *FindBufferLocked(uint32_t hash, Span<const uint8_t> data);
diff --git a/crypto/rsa/internal.h b/crypto/rsa/internal.h index fa56db7..ce057a7 100644 --- a/crypto/rsa/internal.h +++ b/crypto/rsa/internal.h
@@ -28,21 +28,21 @@ size_t param_len, const EVP_MD *md, const EVP_MD *mgf1md); -// rsa_pss_params_get_md returns the hash function used with |params|. This also +// rsa_pss_params_get_md returns the hash function used with `params`. This also // specifies the MGF-1 hash and the salt length because we do not support other // configurations. const EVP_MD *rsa_pss_params_get_md(rsa_pss_params_t params); -// rsa_marshal_pss_params marshals |params| as a DER-encoded RSASSA-PSS-params -// (RFC 4055). It returns one on success and zero on error. If |params| is -// |rsa_pss_params_none|, this function gives an error. +// rsa_marshal_pss_params marshals `params` as a DER-encoded RSASSA-PSS-params +// (RFC 4055). It returns one on success and zero on error. If `params` is +// `rsa_pss_params_none`, this function gives an error. int rsa_marshal_pss_params(CBB *cbb, rsa_pss_params_t params); // rsa_marshal_pss_params decodes a DER-encoded RSASSA-PSS-params // (RFC 4055). It returns one on success and zero on error. On success, it sets -// |*out| to the result. If |allow_explicit_trailer| is non-zero, an explicit +// `*out` to the result. If `allow_explicit_trailer` is non-zero, an explicit // encoding of the trailerField is allowed, although it is not valid DER. This -// function never outputs |rsa_pss_params_none|. +// function never outputs `rsa_pss_params_none`. int rsa_parse_pss_params(CBS *cbs, rsa_pss_params_t *out, int allow_explicit_trailer);
diff --git a/crypto/spake2plus/internal.h b/crypto/spake2plus/internal.h index 7344c57..2ca85ce 100644 --- a/crypto/spake2plus/internal.h +++ b/crypto/spake2plus/internal.h
@@ -64,14 +64,14 @@ // step of the SPAKE2+ protocol. See the following for more details: // https://www.rfc-editor.org/rfc/rfc9383.html#section-3.2 // -// The |password| argument is the mandatory prover password. The |out_w0|, -// |out_w1|, and |out_registration_record| arguments are where the password +// The `password` argument is the mandatory prover password. The `out_w0`, +// `out_w1`, and `out_registration_record` arguments are where the password // verifiers (w0 and w1) and registration record (L) are stored, respectively. -// The prover is given |out_w0| and |out_w1| while the verifier is given -// |out_w0| and |out_registration_record|. +// The prover is given `out_w0` and `out_w1` while the verifier is given +// `out_w0` and `out_registration_record`. // -// To ensure success, |out_w0| and |out_w1| must be of length |kVerifierSize|, -// and |out_registration_record| of size |kRegistrationRecordSize|. +// To ensure success, `out_w0` and `out_w1` must be of length `kVerifierSize`, +// and `out_registration_record` of size `kRegistrationRecordSize`. [[nodiscard]] OPENSSL_EXPORT bool Register( Span<uint8_t> out_w0, Span<uint8_t> out_w1, Span<uint8_t> out_registration_record, Span<const uint8_t> password, @@ -87,10 +87,10 @@ // Init creates a new prover, which can only be used for a single execution of // the protocol. // - // The |context| argument is an application-specific value meant to constrain - // the protocol execution. The |w0| and |w1| arguments are password verifier + // The `context` argument is an application-specific value meant to constrain + // the protocol execution. The `w0` and `w1` arguments are password verifier // values computed during the offline registration phase of the protocol. The - // |id_prover| and |id_verifier| arguments allow optional, opaque names to be + // `id_prover` and `id_verifier` arguments allow optional, opaque names to be // bound into the protocol. See the following for more information about how // these identities may be chosen: // https://www.rfc-editor.org/rfc/rfc9383.html#name-definition-of-spake2 @@ -100,20 +100,20 @@ Span<const uint8_t> w0, Span<const uint8_t> w1, Span<const uint8_t> x = Span<const uint8_t>()); - // GenerateShare computes a SPAKE2+ share and writes it to |out_share|. + // GenerateShare computes a SPAKE2+ share and writes it to `out_share`. // - // This function can only be called once for a given |Prover|. To ensure - // success, |out_share| must be |kShareSize| bytes. + // This function can only be called once for a given `Prover`. To ensure + // success, `out_share` must be `kShareSize` bytes. [[nodiscard]] bool GenerateShare(Span<uint8_t> out_share); // ComputeConfirmation computes a SPAKE2+ key confirmation - // message and writes it to |out_confirm|. It also computes the shared secret - // and writes it to |out_secret|. + // message and writes it to `out_confirm`. It also computes the shared secret + // and writes it to `out_secret`. // - // This function can only be called once for a given |Prover|. + // This function can only be called once for a given `Prover`. // - // To ensure success, |out_confirm| must be |kConfirmSize| bytes - // and |out_secret| must be |kSecretSize| bytes. + // To ensure success, `out_confirm` must be `kConfirmSize` bytes + // and `out_secret` must be `kSecretSize` bytes. [[nodiscard]] bool ComputeConfirmation(Span<uint8_t> out_confirm, Span<uint8_t> out_secret, Span<const uint8_t> peer_share, @@ -146,12 +146,12 @@ // Init creates a new verifier, which can only be used for a single execution // of the protocol. // - // The |context| argument is an application-specific value meant to constrain - // the protocol execution. The |w0| and |registration_record| arguments are - // required, and are computed by the prover via |Register|. Only the prover - // can produce |w0| and |registration_record|, as they require + // The `context` argument is an application-specific value meant to constrain + // the protocol execution. The `w0` and `registration_record` arguments are + // required, and are computed by the prover via `Register`. Only the prover + // can produce `w0` and `registration_record`, as they require // knowledge of the password. The prover must securely transmit this to the - // verifier out-of-band. The |id_prover| and |id_verifier| arguments allow + // verifier out-of-band. The `id_prover` and `id_verifier` arguments allow // optional, opaque names to be bound into the protocol. See the following for // more information about how these identities may be chosen: // https://www.rfc-editor.org/rfc/rfc9383.html#name-definition-of-spake2 @@ -163,23 +163,23 @@ Span<const uint8_t> y = Span<const uint8_t>()); // ProcessProverShare computes a SPAKE2+ share from an input share, - // |prover_share|, and writes it to |out_share|. It also computes the key - // confirmation message and writes it to |out_confirm|. Finally, it computes - // the shared secret and writes it to |out_secret|. + // `prover_share`, and writes it to `out_share`. It also computes the key + // confirmation message and writes it to `out_confirm`. Finally, it computes + // the shared secret and writes it to `out_secret`. // - // This function can only be called once for a given |Verifier|. + // This function can only be called once for a given `Verifier`. // - // To ensure success, |out_share| must be |kShareSize| bytes, |out_confirm| - // must be |kConfirmSize| bytes, and |out_secret| must be |kSecretSize| bytes. + // To ensure success, `out_share` must be `kShareSize` bytes, `out_confirm` + // must be `kConfirmSize` bytes, and `out_secret` must be `kSecretSize` bytes. [[nodiscard]] bool ProcessProverShare(Span<uint8_t> out_share, Span<uint8_t> out_confirm, Span<uint8_t> out_secret, Span<const uint8_t> prover_share); // VerifyProverConfirmation verifies a SPAKE2+ key confirmation message, - // |prover_confirm|. + // `prover_confirm`. // - // This function can only be called once for a given |Verifier|. + // This function can only be called once for a given `Verifier`. [[nodiscard]] bool VerifyProverConfirmation(Span<const uint8_t> peer_confirm); private:
diff --git a/crypto/test/abi_test.h b/crypto/test/abi_test.h index cb084bd..15ae8d2 100644 --- a/crypto/test/abi_test.h +++ b/crypto/test/abi_test.h
@@ -40,7 +40,7 @@ namespace internal { -// DeductionGuard wraps |T| in a template, so that template argument deduction +// DeductionGuard wraps `T` in a template, so that template argument deduction // does not apply to it. This may be used to force C++ to deduce template // arguments from another parameter. template <typename T> @@ -202,9 +202,9 @@ #undef CALLER_STATE_REGISTER }; -// RunTrampoline runs |func| on |argv|, recording ABI errors in |out|. It does -// not perform any type-checking. If |unwind| is true and unwind tests have been -// enabled, |func| is single-stepped under an unwind test. +// RunTrampoline runs `func` on `argv`, recording ABI errors in `out`. It does +// not perform any type-checking. If `unwind` is true and unwind tests have been +// enabled, `func` is single-stepped under an unwind test. crypto_word_t RunTrampoline(Result *out, crypto_word_t func, const crypto_word_t *argv, size_t argc, bool unwind); @@ -224,7 +224,7 @@ // word. When parameters are padded in memory or passed in a larger register, // the unused bits may be undefined or sign- or zero-extended. // - // We could simply cast to |crypto_word_t| everywhere but, on platforms where + // We could simply cast to `crypto_word_t` everywhere but, on platforms where // padding is undefined, we perturb the bits to test the function accounts for // for this. #if defined(OPENSSL_32_BIT) @@ -274,14 +274,14 @@ #endif } -// CheckImpl runs |func| on |args|, recording ABI errors in |out|. If |unwind| -// is true and unwind tests have been enabled, |func| is single-stepped under an +// CheckImpl runs `func` on `args`, recording ABI errors in `out`. If `unwind` +// is true and unwind tests have been enabled, `func` is single-stepped under an // unwind test. // -// It returns the value as a |crypto_word_t| to work around problems when |R| is -// void. |args| is wrapped in a |DeductionGuard| so |func| determines the -// template arguments. Otherwise, |args| may deduce |Args| incorrectly. For -// instance, if |func| takes const int *, and the caller passes an int *, the +// It returns the value as a `crypto_word_t` to work around problems when `R` is +// void. `args` is wrapped in a `DeductionGuard` so `func` determines the +// template arguments. Otherwise, `args` may deduce `Args` incorrectly. For +// instance, if `func` takes const int *, and the caller passes an int *, the // compiler will complain the deduced types do not match. template <typename R, typename... Args> inline crypto_word_t CheckImpl(Result *out, bool unwind, R (*func)(Args...), @@ -302,7 +302,7 @@ #else // To simplify callers when ABI testing support is unavoidable, provide a backup // CheckImpl implementation. It must be specialized for void returns because we -// call |func| directly. +// call `func` directly. template <typename R, typename... Args> inline std::enable_if_t<!std::is_void_v<R>, crypto_word_t> CheckImpl( Result *out, bool /* unwind */, R (*func)(Args...), @@ -324,16 +324,16 @@ // FixVAArgsString takes a string like "f, 1, 2" and returns a string like // "f(1, 2)". // -// This is needed because the |CHECK_ABI| macro below cannot be defined as +// This is needed because the `CHECK_ABI` macro below cannot be defined as // CHECK_ABI(func, ...). The C specification requires that variadic macros bind // at least one variadic argument. Clang, GCC, and MSVC all ignore this, but // there are issues with trailing commas and different behaviors across // compilers. std::string FixVAArgsString(const char *str); -// CheckGTest behaves like |CheckImpl|, but it returns the correct type and -// raises GTest assertions on failure. If |unwind| is true and unwind tests are -// enabled, |func| is single-stepped under an unwind test. +// CheckGTest behaves like `CheckImpl`, but it returns the correct type and +// raises GTest assertions on failure. If `unwind` is true and unwind tests are +// enabled, `func` is single-stepped under an unwind test. template <typename R, typename... Args> inline R CheckGTest(const char *va_args_str, const char *file, int line, bool unwind, R (*func)(Args...), @@ -353,8 +353,8 @@ } // namespace internal -// Check runs |func| on |args| and returns the result. If ABI-testing is -// supported in this build configuration, it writes any ABI failures to |out|. +// Check runs `func` on `args` and returns the result. If ABI-testing is +// supported in this build configuration, it writes any ABI failures to `out`. // Otherwise, it runs the function transparently. template <typename R, typename... Args> inline R Check(Result *out, R (*func)(Args...), @@ -376,7 +376,7 @@ // result. If ABI-testing is supported in this build configuration, it adds a // non-fatal GTest failure if the call did not satisfy ABI requirements. // -// |CHECK_ABI| does return the value and thus may replace any function call, +// `CHECK_ABI` does return the value and thus may replace any function call, // provided it takes only simple parameters. However, it is recommended to test // ABI separately from functional tests of assembly. Fully instrumenting a // function for ABI checking requires single-stepping the function, which is @@ -387,21 +387,21 @@ // only a few instrumented calls are necessary. // // TODO(https://crbug.com/boringssl/259): Most of Windows assembly currently -// fails SEH testing. For now, |CHECK_ABI| behaves like |CHECK_ABI_NO_UNWIND| +// fails SEH testing. For now, `CHECK_ABI` behaves like `CHECK_ABI_NO_UNWIND` // on Windows. Functions which work with unwind testing on Windows should use -// |CHECK_ABI_SEH|. +// `CHECK_ABI_SEH`. #if defined(OPENSSL_WINDOWS) #define CHECK_ABI(...) CHECK_ABI_NO_UNWIND(__VA_ARGS__) #else #define CHECK_ABI(...) CHECK_ABI_SEH(__VA_ARGS__) #endif -// CHECK_ABI_SEH behaves like |CHECK_ABI| but enables unwind testing on Windows. +// CHECK_ABI_SEH behaves like `CHECK_ABI` but enables unwind testing on Windows. #define CHECK_ABI_SEH(...) \ bssl::abi_test::internal::CheckGTest(#__VA_ARGS__, __FILE__, __LINE__, true, \ __VA_ARGS__) -// CHECK_ABI_NO_UNWIND behaves like |CHECK_ABI| but disables unwind testing. +// CHECK_ABI_NO_UNWIND behaves like `CHECK_ABI` but disables unwind testing. #define CHECK_ABI_NO_UNWIND(...) \ bssl::abi_test::internal::CheckGTest(#__VA_ARGS__, __FILE__, __LINE__, \ false, __VA_ARGS__) @@ -416,12 +416,12 @@ extern "C" { -// abi_test_trampoline loads callee-saved registers from |state|, calls |func| -// with |argv|, then saves the callee-saved registers into |state|. It returns -// the result of |func|. If |unwind| is non-zero, this function triggers unwind +// abi_test_trampoline loads callee-saved registers from `state`, calls `func` +// with `argv`, then saves the callee-saved registers into `state`. It returns +// the result of `func`. If `unwind` is non-zero, this function triggers unwind // instrumentation. // -// We give |func| type |crypto_word_t| to avoid tripping MSVC's warning 4191. +// We give `func` type `crypto_word_t` to avoid tripping MSVC's warning 4191. crypto_word_t abi_test_trampoline(crypto_word_t func, abi_test::internal::CallerState *state, const crypto_word_t *argv, size_t argc, @@ -429,22 +429,22 @@ #if defined(OPENSSL_X86_64) // abi_test_unwind_start points at the instruction that starts unwind testing in -// |abi_test_trampoline|. This is the value of the instruction pointer at the -// first |SIGTRAP| during unwind testing. +// `abi_test_trampoline`. This is the value of the instruction pointer at the +// first `SIGTRAP` during unwind testing. // // This symbol is not a function and should not be called. void abi_test_unwind_start(Uncallable); // abi_test_unwind_return points at the instruction immediately after the call in -// |abi_test_trampoline|. When unwinding the function under test, this is the -// expected address in the |abi_test_trampoline| frame. After this address, the -// unwind tester should ignore |SIGTRAP| until |abi_test_unwind_stop|. +// `abi_test_trampoline`. When unwinding the function under test, this is the +// expected address in the `abi_test_trampoline` frame. After this address, the +// unwind tester should ignore `SIGTRAP` until `abi_test_unwind_stop`. // // This symbol is not a function and should not be called. void abi_test_unwind_return(Uncallable); // abi_test_unwind_stop is the value of the instruction pointer at the final -// |SIGTRAP| during unwind testing. +// `SIGTRAP` during unwind testing. // // This symbol is not a function and should not be called. void abi_test_unwind_stop(Uncallable); @@ -471,7 +471,7 @@ int abi_test_get_and_clear_direction_flag(); // abi_test_set_direction_flag sets the direction flag. This does not conform to -// ABI requirements and must only be called within a |CHECK_ABI| guard to avoid +// ABI requirements and must only be called within a `CHECK_ABI` guard to avoid // errors later in the program. int abi_test_set_direction_flag(); #endif // OPENSSL_X86_64 || OPENSSL_X86
diff --git a/crypto/test/der_trailing_data.h b/crypto/test/der_trailing_data.h index 3919575..5e43a1c 100644 --- a/crypto/test/der_trailing_data.h +++ b/crypto/test/der_trailing_data.h
@@ -21,18 +21,18 @@ BSSL_NAMESPACE_BEGIN -// TestDERTrailingData decodes |in| as an arbitrary DER structure. It then calls -// |func| multiple times on different modified versions of |in|, each time with +// TestDERTrailingData decodes `in` as an arbitrary DER structure. It then calls +// `func` multiple times on different modified versions of `in`, each time with // extra data appended to a different constructed element. The extra data will // be a BER EOC, so this is guaranteed to make the structure invalid. // -// |func| is expected to parse its argument and then assert with GTest that the -// parser failed. |n|, passed to |func|, is the number of the constructed -// element that was rewritten, following a pre-order numbering from zero. |func| -// should pass it to |SCOPED_TRACE| to aid debugging. +// `func` is expected to parse its argument and then assert with GTest that the +// parser failed. `n`, passed to `func`, is the number of the constructed +// element that was rewritten, following a pre-order numbering from zero. `func` +// should pass it to `SCOPED_TRACE` to aid debugging. // -// TestDERTrailingData returns whether it successful rewrote |in| and called -// |func| for every constructed element. +// TestDERTrailingData returns whether it successful rewrote `in` and called +// `func` for every constructed element. bool TestDERTrailingData( Span<const uint8_t> in, std::function<void(Span<const uint8_t> rewritten, size_t n)> func);
diff --git a/crypto/test/file_test.h b/crypto/test/file_test.h index 6708cea..f82124f 100644 --- a/crypto/test/file_test.h +++ b/crypto/test/file_test.h
@@ -72,9 +72,9 @@ // // Additional blank lines and lines beginning with # are ignored. // -// Functions in this module freely output to |stderr| on failure. Tests should +// Functions in this module freely output to `stderr` on failure. Tests should // also do so, and it is recommended they include the corresponding test's line -// number in any output. |PrintLine| does this automatically. +// number in any output. `PrintLine` does this automatically. // // Each attribute in a test and all instructions applying to it must be // consumed. When a test completes, if any attributes or instructions haven't @@ -103,7 +103,7 @@ // callback is called for each test. It should get the parameters from this // object and signal any errors by returning false. FileTestFunc callback = nullptr; - // arg is an opaque pointer that is passed to |callback|. + // arg is an opaque pointer that is passed to `callback`. void *arg = nullptr; // silent suppressed the "PASS" string that is otherwise printed after // successful runs. @@ -121,10 +121,10 @@ bool is_kas_test); ~FileTest(); - // ReadNext reads the next test from the file. It returns |kReadSuccess| if - // successfully reading a test and |kReadEOF| at the end of the file. On + // ReadNext reads the next test from the file. It returns `kReadSuccess` if + // successfully reading a test and `kReadEOF` at the end of the file. On // error or if the previous test had unconsumed attributes, it returns - // |kReadError|. + // `kReadError`. ReadResult ReadNext(); // PrintLine is a variant of printf which prepends the line number and appends @@ -138,26 +138,26 @@ // GetParameter returns the value of the first attribute of the current test. const std::string &GetParameter(); - // HasAttribute returns true if the current test has an attribute named |key|. + // HasAttribute returns true if the current test has an attribute named `key`. bool HasAttribute(std::string_view key); - // GetAttribute looks up the attribute with key |key|. It sets |*out_value| to + // GetAttribute looks up the attribute with key `key`. It sets `*out_value` to // the value and returns true if it exists and returns false with an error to - // |stderr| otherwise. + // `stderr` otherwise. bool GetAttribute(std::string *out_value, std::string_view key); - // GetAttributeOrDie looks up the attribute with key |key| and aborts if it is - // missing. It should only be used after a |HasAttribute| call. + // GetAttributeOrDie looks up the attribute with key `key` and aborts if it is + // missing. It should only be used after a `HasAttribute` call. const std::string &GetAttributeOrDie(std::string_view key); - // IgnoreAttribute marks the attribute with key |key| as used. + // IgnoreAttribute marks the attribute with key `key` as used. void IgnoreAttribute(std::string_view key) { HasAttribute(key); } - // GetBytes looks up the attribute with key |key| and decodes it as a byte - // string. On success, it writes the result to |*out| and returns - // true. Otherwise it returns false with an error to |stderr|. The value may + // GetBytes looks up the attribute with key `key` and decodes it as a byte + // string. On success, it writes the result to `*out` and returns + // true. Otherwise it returns false with an error to `stderr`. The value may // be either a hexadecimal string or a quoted ASCII string. It returns true on - // success and returns false with an error to |stderr| on failure. + // success and returns false with an error to `stderr` on failure. bool GetBytes(std::vector<uint8_t> *out, std::string_view key); // AtNewInstructionBlock returns true if the current test was immediately @@ -167,20 +167,20 @@ // HasInstruction returns true if the current test has an instruction. bool HasInstruction(std::string_view key); - // IgnoreInstruction marks the instruction with key |key| as used. + // IgnoreInstruction marks the instruction with key `key` as used. void IgnoreInstruction(std::string_view key) { HasInstruction(key); } // IgnoreAllUnusedInstructions disables checking for unused instructions. void IgnoreAllUnusedInstructions(); - // GetInstruction looks up the instruction with key |key|. It sets - // |*out_value| to the value (empty string if the instruction has no value) - // and returns true if it exists and returns false with an error to |stderr| + // GetInstruction looks up the instruction with key `key`. It sets + // `*out_value` to the value (empty string if the instruction has no value) + // and returns true if it exists and returns false with an error to `stderr` // otherwise. bool GetInstruction(std::string *out_value, std::string_view key); - // GetInstructionOrDie looks up the instruction with key |key| and aborts if - // it is missing. It should only be used after a |HasInstruction| call. + // GetInstructionOrDie looks up the instruction with key `key` and aborts if + // it is missing. It should only be used after a `HasInstruction` call. const std::string &GetInstructionOrDie(std::string_view key); // GetInstructionBytes behaves like GetBytes, but looks up the corresponding @@ -245,8 +245,8 @@ FileTest &operator=(const FileTest &) = delete; }; -// FileTestMain runs a file-based test out of |path| and returns an exit code -// suitable to return out of |main|. |run_test| should return true on pass and +// FileTestMain runs a file-based test out of `path` and returns an exit code +// suitable to return out of `main`. `run_test` should return true on pass and // false on failure. FileTestMain also implements common handling of the 'Error' // attribute. A test with that attribute is expected to fail. The value of the // attribute is the reason string of the expected OpenSSL error code. @@ -261,7 +261,7 @@ // FileTestMain accepts a larger number of options via a struct. int FileTestMain(const FileTest::Options &opts); -// FileTestGTest behaves like FileTestMain, but for GTest. |path| must be the +// FileTestGTest behaves like FileTestMain, but for GTest. `path` must be the // name of a test file embedded in the test binary. void FileTestGTest(const char *path, std::function<void(FileTest *)> run_test);
diff --git a/crypto/test/file_util.h b/crypto/test/file_util.h index 78c782c..5aa3884 100644 --- a/crypto/test/file_util.h +++ b/crypto/test/file_util.h
@@ -87,20 +87,20 @@ TemporaryFile(TemporaryFile &other) { *this = std::move(other); } TemporaryFile& operator=(TemporaryFile&&other) { - // Ensure |path_| is empty so it doesn't try to delete the File. + // Ensure `path_` is empty so it doesn't try to delete the File. path_ = std::exchange(other.path_, {}); return *this; } // Init initializes the temporary file with the specified content. It returns // true on success and false on error. On error, callers should call - // |IgnoreTempFileErrors| to determine whether to ignore the error. + // `IgnoreTempFileErrors` to determine whether to ignore the error. bool Init(bssl::Span<const uint8_t> content = {}); bool Init(std::string_view content) { return Init(bssl::StringAsBytes(content)); } - // Open opens the file as a |FILE| with the specified mode. + // Open opens the file as a `FILE` with the specified mode. ScopedFILE Open(const char *mode) const; // Open opens the file as a file descriptor with the specified flags. @@ -121,14 +121,14 @@ TemporaryDirectory(TemporaryDirectory &other) { *this = std::move(other); } TemporaryDirectory& operator=(TemporaryDirectory&&other) { - // Ensure |other_| is empty so it doesn't try to delete the directory. + // Ensure `other_` is empty so it doesn't try to delete the directory. path_ = std::exchange(other.path_, {}); files_ = std::exchange(other.files_, {}); return *this; } // Init initializes the temporary directory. It returns true on success and - // false on error. On error, callers should call |IgnoreTempFileErrors| to + // false on error. On error, callers should call `IgnoreTempFileErrors` to // determine whether to ignore the error. bool Init();
diff --git a/crypto/test/gtest_main.h b/crypto/test/gtest_main.h index 8cb2900..4e7aba5 100644 --- a/crypto/test/gtest_main.h +++ b/crypto/test/gtest_main.h
@@ -76,7 +76,7 @@ } #else // Some tests create pipes. We check return values, so avoid being killed by - // |SIGPIPE|. + // `SIGPIPE`. signal(SIGPIPE, SIG_IGN); #endif
diff --git a/crypto/test/test_data.h b/crypto/test/test_data.h index a1e3ce1..0ccf300 100644 --- a/crypto/test/test_data.h +++ b/crypto/test/test_data.h
@@ -17,7 +17,7 @@ #include <string> -// GetTestData returns the test data for |path|, or aborts on error. |path| +// GetTestData returns the test data for `path`, or aborts on error. `path` // must be a slash-separated path, relative to the BoringSSL source tree. By // default, this is implemented by reading from the filesystem, relative to // the BORINGSSL_TEST_DATA_ROOT environment variable, or the current working
diff --git a/crypto/test/test_util.h b/crypto/test/test_util.h index 4433cc3..af6c6ec 100644 --- a/crypto/test/test_util.h +++ b/crypto/test/test_util.h
@@ -31,8 +31,8 @@ #include "../internal.h" -// hexdump writes |msg| to |fp| followed by the hex encoding of |len| bytes -// from |in|. +// hexdump writes `msg` to `fp` followed by the hex encoding of `len` bytes +// from `in`. void hexdump(FILE *fp, const char *msg, const void *in, size_t len); // Bytes is a wrapper over a byte slice which may be compared for equality. This @@ -64,23 +64,23 @@ std::ostream &operator<<(std::ostream &os, const Bytes &in); -// DecodeHex decodes |in| from hexadecimal and writes the output to |out|. It -// returns true on success and false if |in| is not a valid hexadecimal byte +// DecodeHex decodes `in` from hexadecimal and writes the output to `out`. It +// returns true on success and false if `in` is not a valid hexadecimal byte // string. bool DecodeHex(std::vector<uint8_t> *out, std::string_view in); -// EncodeHex returns |in| encoded in hexadecimal. +// EncodeHex returns `in` encoded in hexadecimal. std::string EncodeHex(bssl::Span<const uint8_t> in); -// ErrorEquals asserts that |err| is an error with library |lib| and reason -// |reason|. +// ErrorEquals asserts that `err` is an error with library `lib` and reason +// `reason`. testing::AssertionResult ErrorEquals(uint32_t err, int lib, int reason); -// HexToBignum decodes |hex| as a hexadecimal, big-endian, unsigned integer and -// returns it as a |BIGNUM|, or nullptr on error. +// HexToBignum decodes `hex` as a hexadecimal, big-endian, unsigned integer and +// returns it as a `BIGNUM`, or nullptr on error. bssl::UniquePtr<BIGNUM> HexToBIGNUM(const char *hex); -// BIGNUMToHex returns |bn| as a hexadecimal, big-endian, unsigned integer. +// BIGNUMToHex returns `bn` as a hexadecimal, big-endian, unsigned integer. std::string BIGNUMToHex(const BIGNUM *bn);
diff --git a/crypto/test/wycheproof_util.h b/crypto/test/wycheproof_util.h index e9d0190..c569f0d 100644 --- a/crypto/test/wycheproof_util.h +++ b/crypto/test/wycheproof_util.h
@@ -37,11 +37,11 @@ // IsValid returns true if the Wycheproof test should be considered valid. A // test result of "acceptable" is treated as valid if all flags are included - // in |acceptable_flags| and invalid otherwise. + // in `acceptable_flags` and invalid otherwise. bool IsValid(const std::vector<std::string> &acceptable_flags = {}) const; }; -// GetWycheproofResult sets |*out| to the parsed "result" and "flags" keys of |t|. +// GetWycheproofResult sets `*out` to the parsed "result" and "flags" keys of `t`. bool GetWycheproofResult(FileTest *t, WycheproofResult *out); // GetWycheproofDigest returns a digest function using the Wycheproof name, or
diff --git a/crypto/trust_token/internal.h b/crypto/trust_token/internal.h index d3afc17..cb3aed5 100644 --- a/crypto/trust_token/internal.h +++ b/crypto/trust_token/internal.h
@@ -44,8 +44,8 @@ typedef struct { // TODO(https://crbug.com/boringssl/334): These should store - // |bssl::EC_PRECOMP| so that |TRUST_TOKEN_finish_issuance| can use - // |ec_point_mul_scalar_precomp|. + // `bssl::EC_PRECOMP` so that `TRUST_TOKEN_finish_issuance` can use + // `ec_point_mul_scalar_precomp`. bssl::EC_AFFINE pub0; bssl::EC_AFFINE pub1; bssl::EC_AFFINE pubs; @@ -75,7 +75,7 @@ bssl::EC_AFFINE Tp; } TRUST_TOKEN_PRETOKEN; -// TRUST_TOKEN_PRETOKEN_free releases the memory associated with |token|. +// TRUST_TOKEN_PRETOKEN_free releases the memory associated with `token`. OPENSSL_EXPORT void TRUST_TOKEN_PRETOKEN_free(TRUST_TOKEN_PRETOKEN *token); DEFINE_NAMESPACED_STACK_OF(TRUST_TOKEN_PRETOKEN) @@ -88,8 +88,8 @@ // construction with validity verification, described in appendix H, // construction 6. -// The following functions implement the corresponding |TRUST_TOKENS_METHOD| -// functions for |TRUST_TOKENS_experiment_v1|'s PMBTokens construction which +// The following functions implement the corresponding `TRUST_TOKENS_METHOD` +// functions for `TRUST_TOKENS_experiment_v1`'s PMBTokens construction which // uses P-384. int pmbtoken_exp1_generate_key(CBB *out_private, CBB *out_public); int pmbtoken_exp1_derive_key_from_secret(CBB *out_private, CBB *out_public, @@ -120,8 +120,8 @@ // function is used to confirm H was computed as expected. OPENSSL_EXPORT int pmbtoken_exp1_get_h_for_testing(uint8_t out[97]); -// The following functions implement the corresponding |TRUST_TOKENS_METHOD| -// functions for |TRUST_TOKENS_experiment_v2|'s PMBTokens construction which +// The following functions implement the corresponding `TRUST_TOKENS_METHOD` +// functions for `TRUST_TOKENS_experiment_v2`'s PMBTokens construction which // uses P-384. int pmbtoken_exp2_generate_key(CBB *out_private, CBB *out_public); int pmbtoken_exp2_derive_key_from_secret(CBB *out_private, CBB *out_public, @@ -152,8 +152,8 @@ // function is used to confirm H was computed as expected. OPENSSL_EXPORT int pmbtoken_exp2_get_h_for_testing(uint8_t out[97]); -// The following functions implement the corresponding |TRUST_TOKENS_METHOD| -// functions for |TRUST_TOKENS_pst_v1|'s PMBTokens construction which uses +// The following functions implement the corresponding `TRUST_TOKENS_METHOD` +// functions for `TRUST_TOKENS_pst_v1`'s PMBTokens construction which uses // P-384. int pmbtoken_pst1_generate_key(CBB *out_private, CBB *out_public); int pmbtoken_pst1_derive_key_from_secret(CBB *out_private, CBB *out_public, @@ -191,11 +191,11 @@ // and provide anonymous tokens. This implementation uses TrustToken DSTs and // the DLEQ batching primitive from // https://eprint.iacr.org/2020/072/20200324:214215. -// VOPRF only uses the |pub|' field of the TRUST_TOKEN_CLIENT_KEY and -// |xs|/|pubs| fields of the TRUST_TOKEN_ISSUER_KEY. +// VOPRF only uses the `pub`' field of the TRUST_TOKEN_CLIENT_KEY and +// `xs`/`pubs` fields of the TRUST_TOKEN_ISSUER_KEY. -// The following functions implement the corresponding |TRUST_TOKENS_METHOD| -// functions for |TRUST_TOKENS_experiment_v2|'s VOPRF construction which uses +// The following functions implement the corresponding `TRUST_TOKENS_METHOD` +// functions for `TRUST_TOKENS_experiment_v2`'s VOPRF construction which uses // P-384. int voprf_exp2_generate_key(CBB *out_private, CBB *out_public); int voprf_exp2_derive_key_from_secret(CBB *out_private, CBB *out_public, @@ -221,8 +221,8 @@ size_t token_len, int include_message, const uint8_t *msg, size_t msg_len); -// The following functions implement the corresponding |TRUST_TOKENS_METHOD| -// functions for |TRUST_TOKENS_pst_v1|'s VOPRF construction which uses P-384. +// The following functions implement the corresponding `TRUST_TOKENS_METHOD` +// functions for `TRUST_TOKENS_pst_v1`'s VOPRF construction which uses P-384. int voprf_pst1_generate_key(CBB *out_private, CBB *out_public); int voprf_pst1_derive_key_from_secret(CBB *out_private, CBB *out_public, const uint8_t *secret, size_t secret_len); @@ -259,33 +259,33 @@ struct trust_token_method_st { // generate_key generates a fresh keypair and writes their serialized - // forms into |out_private| and |out_public|. It returns one on success and + // forms into `out_private` and `out_public`. It returns one on success and // zero on failure. int (*generate_key)(CBB *out_private, CBB *out_public); // derive_key_from_secret deterministically derives a keypair based on - // |secret| and writes their serialized forms into |out_private| and - // |out_public|. It returns one on success and zero on failure. + // `secret` and writes their serialized forms into `out_private` and + // `out_public`. It returns one on success and zero on failure. int (*derive_key_from_secret)(CBB *out_private, CBB *out_public, const uint8_t *secret, size_t secret_len); - // client_key_from_bytes decodes a client key from |in| and sets |key| + // client_key_from_bytes decodes a client key from `in` and sets `key` // to the resulting key. It returns one on success and zero // on failure. int (*client_key_from_bytes)(bssl::TRUST_TOKEN_CLIENT_KEY *key, const uint8_t *in, size_t len); - // issuer_key_from_bytes decodes a issuer key from |in| and sets |key| + // issuer_key_from_bytes decodes a issuer key from `in` and sets `key` // to the resulting key. It returns one on success and zero // on failure. int (*issuer_key_from_bytes)(bssl::TRUST_TOKEN_ISSUER_KEY *key, const uint8_t *in, size_t len); - // blind generates a new issuance request for |count| tokens. If - // |include_message| is set, then |msg| is used to derive the token nonces. On - // success, it returns a newly-allocated |STACK_OF(TRUST_TOKEN_PRETOKEN)| and - // writes a request to the issuer to |cbb|. On failure, it returns NULL. The - // |STACK_OF(TRUST_TOKEN_PRETOKEN)|s should be passed to |pmbtoken_unblind| + // blind generates a new issuance request for `count` tokens. If + // `include_message` is set, then `msg` is used to derive the token nonces. On + // success, it returns a newly-allocated `STACK_OF(TRUST_TOKEN_PRETOKEN)` and + // writes a request to the issuer to `cbb`. On failure, it returns NULL. The + // `STACK_OF(TRUST_TOKEN_PRETOKEN)`s should be passed to `pmbtoken_unblind` // when the server responds. // // This function implements the AT.Usr0 operation. @@ -293,9 +293,9 @@ int include_message, const uint8_t *msg, size_t msg_len); - // sign parses a request for |num_requested| tokens from |cbs| and - // issues |num_to_issue| tokens with |key| and a private metadata value of - // |private_metadata|. It then writes the response to |cbb|. It returns one on + // sign parses a request for `num_requested` tokens from `cbs` and + // issues `num_to_issue` tokens with `key` and a private metadata value of + // `private_metadata`. It then writes the response to `cbb`. It returns one on // success and zero on failure. // // This function implements the AT.Sig operation. @@ -303,11 +303,11 @@ size_t num_requested, size_t num_to_issue, uint8_t private_metadata); - // unblind processes an issuance response for |count| tokens from |cbs| - // and unblinds the signed tokens. |pretokens| are the pre-tokens returned - // from the corresponding |blind| call. On success, the function returns a - // newly-allocated |STACK_OF(TRUST_TOKEN)| containing the resulting tokens. - // Each token's serialization will have |key_id| prepended. Otherwise, it + // unblind processes an issuance response for `count` tokens from `cbs` + // and unblinds the signed tokens. `pretokens` are the pre-tokens returned + // from the corresponding `blind` call. On success, the function returns a + // newly-allocated `STACK_OF(TRUST_TOKEN)` containing the resulting tokens. + // Each token's serialization will have `key_id` prepended. Otherwise, it // returns NULL. // // This function implements the AT.Usr1 operation. @@ -316,11 +316,11 @@ const bssl::StackOfTrustTokenPretoken *pretokens, CBS *cbs, size_t count, uint32_t key_id); - // read parses a token from |token| and verifies it using |key|. If - // |include_message| is set, then the nonce is derived from |msg| and the salt + // read parses a token from `token` and verifies it using `key`. If + // `include_message` is set, then the nonce is derived from `msg` and the salt // in the token. On success, it returns one and stores the nonce and private - // metadata bit in |out_nonce| and |*out_private_metadata|. Otherwise, it - // returns zero. Note that, unlike the output of |unblind|, |token| does not + // metadata bit in `out_nonce` and `*out_private_metadata`. Otherwise, it + // returns zero. Note that, unlike the output of `unblind`, `token` does not // have a four-byte key ID prepended. int (*read)(const bssl::TRUST_TOKEN_ISSUER_KEY *key, uint8_t out_nonce[TRUST_TOKEN_NONCE_SIZE], @@ -363,7 +363,7 @@ // keys is the set of public keys that are supported by the client for // issuance/redemptions. - // TODO(crbug.com/42290036): Replace this and |num_keys| with an + // TODO(crbug.com/42290036): Replace this and `num_keys` with an // InplaceVector. struct bssl::trust_token_client_key_st keys[6];
diff --git a/crypto/x509/internal.h b/crypto/x509/internal.h index 7257fcf..c1a9dc4 100644 --- a/crypto/x509/internal.h +++ b/crypto/x509/internal.h
@@ -46,9 +46,9 @@ int x509_marshal_public_key(CBB *cbb, const X509_PUBKEY *in); int x509_pubkey_set1(X509_PUBKEY *key, EVP_PKEY *pkey); -// X509_PUBKEY is an |ASN1_ITEM| whose ASN.1 type is SubjectPublicKeyInfo and C -// type is |X509_PUBKEY*|. -// TODO(crbug.com/42290417): Remove this when |X509| and |X509_REQ| no longer +// X509_PUBKEY is an `ASN1_ITEM` whose ASN.1 type is SubjectPublicKeyInfo and C +// type is `X509_PUBKEY*`. +// TODO(crbug.com/42290417): Remove this when `X509` and `X509_REQ` no longer // depend on the tables. DECLARE_ASN1_ITEM(X509_PUBKEY) @@ -62,8 +62,8 @@ BSSL_NAMESPACE_BEGIN -// X509_NAME_ENTRY is an |ASN1_ITEM| whose ASN.1 type is AttributeTypeAndValue -// (RFC 5280) and C type is |X509_NAME_ENTRY*|. +// X509_NAME_ENTRY is an `ASN1_ITEM` whose ASN.1 type is AttributeTypeAndValue +// (RFC 5280) and C type is `X509_NAME_ENTRY*`. DECLARE_ASN1_ITEM(X509_NAME_ENTRY) struct X509_NAME_CACHE { @@ -90,8 +90,8 @@ BSSL_NAMESPACE_BEGIN -// X509_ATTRIBUTE is an |ASN1_ITEM| whose ASN.1 type is Attribute (RFC 2986) and -// C type is |X509_ATTRIBUTE*|. +// X509_ATTRIBUTE is an `ASN1_ITEM` whose ASN.1 type is Attribute (RFC 2986) and +// C type is `X509_ATTRIBUTE*`. DECLARE_ASN1_ITEM(X509_ATTRIBUTE) typedef struct x509_cert_aux_st { @@ -111,14 +111,14 @@ ASN1_OCTET_STRING *value; } /* X509_EXTENSION */; -// X509_EXTENSION is an |ASN1_ITEM| whose ASN.1 type is X.509 Extension (RFC -// 5280) and C type is |X509_EXTENSION*|. +// X509_EXTENSION is an `ASN1_ITEM` whose ASN.1 type is X.509 Extension (RFC +// 5280) and C type is `X509_EXTENSION*`. DECLARE_ASN1_ITEM(X509_EXTENSION) BSSL_NAMESPACE_BEGIN -// X509_EXTENSIONS is an |ASN1_ITEM| whose ASN.1 type is SEQUENCE of Extension -// (RFC 5280) and C type is |STACK_OF(X509_EXTENSION)*|. +// X509_EXTENSIONS is an `ASN1_ITEM` whose ASN.1 type is SEQUENCE of Extension +// (RFC 5280) and C type is `STACK_OF(X509_EXTENSION)*`. DECLARE_ASN1_ITEM(X509_EXTENSIONS) class X509Impl : public x509_st, public RefCounted<X509Impl> { @@ -126,7 +126,7 @@ X509Impl(); // TBSCertificate fields: - uint8_t version = X509_VERSION_1; // One of the |X509_VERSION_*| constants. + uint8_t version = X509_VERSION_1; // One of the `X509_VERSION_*` constants. ASN1_INTEGER serialNumber; X509_ALGOR tbs_sig_alg; X509Name issuer; @@ -142,8 +142,8 @@ ASN1_BIT_STRING signature; // Other state: // buf, if not nullptr, contains a copy of the serialized Certificate. - // TODO(davidben): Now every parsed |X509| has an underlying |CRYPTO_BUFFER|, - // but |X509|s created peacemeal do not. Can we make this more uniform? + // TODO(davidben): Now every parsed `X509` has an underlying `CRYPTO_BUFFER`, + // but `X509`s created peacemeal do not. Can we make this more uniform? CRYPTO_BUFFER *buf = nullptr; CRYPTO_EX_DATA ex_data; // These contain copies of various extension values @@ -167,8 +167,8 @@ int x509_marshal_tbs_cert(CBB *cbb, const X509 *x509); -// X509 is an |ASN1_ITEM| whose ASN.1 type is X.509 Certificate (RFC 5280) and C -// type is |X509*|. +// X509 is an `ASN1_ITEM` whose ASN.1 type is X.509 Certificate (RFC 5280) and C +// type is `X509*`. DECLARE_ASN1_ITEM(X509) typedef struct { @@ -192,8 +192,8 @@ BSSL_NAMESPACE_BEGIN -// X509_REQ is an |ASN1_ITEM| whose ASN.1 type is CertificateRequest (RFC 2986) -// and C type is |X509_REQ*|. +// X509_REQ is an `ASN1_ITEM` whose ASN.1 type is CertificateRequest (RFC 2986) +// and C type is `X509_REQ*`. DECLARE_ASN1_ITEM(X509_REQ) BSSL_NAMESPACE_END @@ -208,9 +208,9 @@ BSSL_NAMESPACE_BEGIN -// X509_REVOKED is an |ASN1_ITEM| whose ASN.1 type is an element of the +// X509_REVOKED is an `ASN1_ITEM` whose ASN.1 type is an element of the // revokedCertificates field of TBSCertList (RFC 5280) and C type is -// |X509_REVOKED*|. +// `X509_REVOKED*`. DECLARE_ASN1_ITEM(X509_REVOKED) typedef struct { @@ -261,16 +261,16 @@ BSSL_NAMESPACE_BEGIN -// X509_CRL is an |ASN1_ITEM| whose ASN.1 type is X.509 CertificateList (RFC -// 5280) and C type is |X509_CRL*|. +// X509_CRL is an `ASN1_ITEM` whose ASN.1 type is X.509 CertificateList (RFC +// 5280) and C type is `X509_CRL*`. DECLARE_ASN1_ITEM(X509_CRL) -// GENERAL_NAME is an |ASN1_ITEM| whose ASN.1 type is GeneralName and C type is -// |GENERAL_NAME*|. +// GENERAL_NAME is an `ASN1_ITEM` whose ASN.1 type is GeneralName and C type is +// `GENERAL_NAME*`. DECLARE_ASN1_ITEM(GENERAL_NAME) -// GENERAL_NAMES is an |ASN1_ITEM| whose ASN.1 type is SEQUENCE OF GeneralName -// and C type is |GENERAL_NAMES*|, aka |STACK_OF(GENERAL_NAME)*|. +// GENERAL_NAMES is an `ASN1_ITEM` whose ASN.1 type is SEQUENCE OF GeneralName +// and C type is `GENERAL_NAMES*`, aka `STACK_OF(GENERAL_NAME)*`. DECLARE_ASN1_ITEM(GENERAL_NAMES) BSSL_NAMESPACE_END @@ -305,12 +305,12 @@ BSSL_NAMESPACE_BEGIN -// NETSCAPE_SPKI is an |ASN1_ITEM| whose ASN.1 type is -// SignedPublicKeyAndChallenge and C type is |NETSCAPE_SPKI*|. +// NETSCAPE_SPKI is an `ASN1_ITEM` whose ASN.1 type is +// SignedPublicKeyAndChallenge and C type is `NETSCAPE_SPKI*`. DECLARE_ASN1_ITEM(NETSCAPE_SPKI) -// NETSCAPE_SPKAC is an |ASN1_ITEM| whose ASN.1 type is PublicKeyAndChallenge -// and C type is |NETSCAPE_SPKAC*|. +// NETSCAPE_SPKAC is an `ASN1_ITEM` whose ASN.1 type is PublicKeyAndChallenge +// and C type is `NETSCAPE_SPKAC*`. DECLARE_ASN1_ITEM(NETSCAPE_SPKAC) BSSL_NAMESPACE_END @@ -375,7 +375,7 @@ X509_VERIFY_PARAM *param; // trusted_stack, if non-NULL, is a set of trusted certificates to consider - // instead of those from |X509_STORE|. + // instead of those from `X509_STORE`. STACK_OF(X509) *trusted_stack; // Callbacks for various operations @@ -406,20 +406,20 @@ // RSA-PSS functions. -// x509_rsa_pss_to_ctx configures |ctx| for an RSA-PSS operation based on -// signature algorithm parameters in |sigalg| (which must have type -// |NID_rsassaPss|) and key |pkey|. It returns one on success and zero on +// x509_rsa_pss_to_ctx configures `ctx` for an RSA-PSS operation based on +// signature algorithm parameters in `sigalg` (which must have type +// `NID_rsassaPss`) and key `pkey`. It returns one on success and zero on // error. int x509_rsa_pss_to_ctx(EVP_MD_CTX *ctx, const X509_ALGOR *sigalg, EVP_PKEY *pkey); -// x509_rsa_pss_to_ctx sets |algor| to the signature algorithm parameters for -// |ctx|, which must have been configured for an RSA-PSS signing operation. It +// x509_rsa_pss_to_ctx sets `algor` to the signature algorithm parameters for +// `ctx`, which must have been configured for an RSA-PSS signing operation. It // returns one on success and zero on error. int x509_rsa_ctx_to_pss(EVP_MD_CTX *ctx, X509_ALGOR *algor); // x509_print_rsa_pss_params prints a human-readable representation of RSA-PSS -// parameters in |sigalg| to |bp|. It returns one on success and zero on +// parameters in `sigalg` to `bp`. It returns one on success and zero on // error. int x509_print_rsa_pss_params(BIO *bp, const X509_ALGOR *sigalg, int indent, ASN1_PCTX *pctx); @@ -427,25 +427,25 @@ // Signature algorithm functions. -// x509_digest_sign_algorithm encodes the signing parameters of |ctx| as an -// AlgorithmIdentifier and saves the result in |algor|. It returns one on +// x509_digest_sign_algorithm encodes the signing parameters of `ctx` as an +// AlgorithmIdentifier and saves the result in `algor`. It returns one on // success, or zero on error. int x509_digest_sign_algorithm(EVP_MD_CTX *ctx, X509_ALGOR *algor); -// x509_digest_verify_init sets up |ctx| for a signature verification operation -// with public key |pkey| and parameters from |algor|. The |ctx| argument must -// have been initialised with |EVP_MD_CTX_init|. It returns one on success, or +// x509_digest_verify_init sets up `ctx` for a signature verification operation +// with public key `pkey` and parameters from `algor`. The `ctx` argument must +// have been initialised with `EVP_MD_CTX_init`. It returns one on success, or // zero on error. int x509_digest_verify_init(EVP_MD_CTX *ctx, const X509_ALGOR *sigalg, EVP_PKEY *pkey); -// x509_verify_signature verifies a |signature| using |sigalg| and |pkey| over -// |in|. It returns one if the signature is valid and zero on error. +// x509_verify_signature verifies a `signature` using `sigalg` and `pkey` over +// `in`. It returns one if the signature is valid and zero on error. int x509_verify_signature(const X509_ALGOR *sigalg, const ASN1_BIT_STRING *signature, Span<const uint8_t> in, EVP_PKEY *pkey); -// x509_sign_to_bit_string signs |in| using |ctx| and saves the result in |out|. +// x509_sign_to_bit_string signs `in` using `ctx` and saves the result in `out`. // It returns the length of the signature on success and zero on error. int x509_sign_to_bit_string(EVP_MD_CTX *ctx, ASN1_BIT_STRING *out, Span<const uint8_t> in); @@ -453,124 +453,124 @@ // Path-building functions. -// X509_policy_check checks certificate policies in |certs|. |user_policies| is -// the user-initial-policy-set. If |user_policies| is NULL or empty, it is -// interpreted as anyPolicy. |flags| is a set of |X509_V_FLAG_*| values to -// apply. It returns |X509_V_OK| on success and |X509_V_ERR_*| on error. It -// additionally sets |*out_current_cert| to the certificate where the error +// X509_policy_check checks certificate policies in `certs`. `user_policies` is +// the user-initial-policy-set. If `user_policies` is NULL or empty, it is +// interpreted as anyPolicy. `flags` is a set of `X509_V_FLAG_*` values to +// apply. It returns `X509_V_OK` on success and `X509_V_ERR_*` on error. It +// additionally sets `*out_current_cert` to the certificate where the error // occurred. If the function succeeded, or the error applies to the entire -// chain, it sets |*out_current_cert| to NULL. +// chain, it sets `*out_current_cert` to NULL. int X509_policy_check(const STACK_OF(X509) *certs, const STACK_OF(ASN1_OBJECT) *user_policies, unsigned long flags, X509 **out_current_cert); -// x509_check_issued_with_callback calls |X509_check_issued|, but allows the +// x509_check_issued_with_callback calls `X509_check_issued`, but allows the // verify callback to override the result. It returns one on success and zero on // error. // // TODO(davidben): Reduce the scope of the verify callback and remove this. The -// callback only runs with |X509_V_FLAG_CB_ISSUER_CHECK|, which is only used by +// callback only runs with `X509_V_FLAG_CB_ISSUER_CHECK`, which is only used by // one internal project and rust-openssl, who use it by mistake. int x509_check_issued_with_callback(X509_STORE_CTX *ctx, const X509 *x, const X509 *issuer); -// x509v3_bytes_to_hex encodes |len| bytes from |in| to hex and returns a +// x509v3_bytes_to_hex encodes `len` bytes from `in` to hex and returns a // newly-allocated NUL-terminated string containing the result, or NULL on // allocation error. // -// This function was historically named |hex_to_string| in OpenSSL. Despite the -// name, |hex_to_string| converted to hex. +// This function was historically named `hex_to_string` in OpenSSL. Despite the +// name, `hex_to_string` converted to hex. OPENSSL_EXPORT char *x509v3_bytes_to_hex(const uint8_t *in, size_t len); -// x509v3_hex_string_to_bytes decodes |str| in hex and returns a newly-allocated -// array containing the result, or NULL on error. On success, it sets |*len| to +// x509v3_hex_string_to_bytes decodes `str` in hex and returns a newly-allocated +// array containing the result, or NULL on error. On success, it sets `*len` to // the length of the result. Colon separators between bytes in the input are // allowed and ignored. // -// This function was historically named |string_to_hex| in OpenSSL. Despite the -// name, |string_to_hex| converted from hex. +// This function was historically named `string_to_hex` in OpenSSL. Despite the +// name, `string_to_hex` converted from hex. unsigned char *x509v3_hex_to_bytes(const char *str, size_t *len); -// x509v3_conf_name_matches returns one if |name| is equal to |cmp| or begins -// with |cmp| followed by '.', and zero otherwise. +// x509v3_conf_name_matches returns one if `name` is equal to `cmp` or begins +// with `cmp` followed by '.', and zero otherwise. int x509v3_conf_name_matches(const char *name, const char *cmp); -// x509v3_looks_like_dns_name returns one if |in| looks like a DNS name and zero +// x509v3_looks_like_dns_name returns one if `in` looks like a DNS name and zero // otherwise. OPENSSL_EXPORT int x509v3_looks_like_dns_name(const unsigned char *in, size_t len); // x509v3_cache_extensions fills in a number of fields relating to X.509 -// extensions in |x|. It returns one on success and zero if some extensions were +// extensions in `x`. It returns one on success and zero if some extensions were // invalid. OPENSSL_EXPORT int x509v3_cache_extensions(X509 *x); -// x509v3_a2i_ipadd decodes |ipasc| as an IPv4 or IPv6 address. IPv6 addresses +// x509v3_a2i_ipadd decodes `ipasc` as an IPv4 or IPv6 address. IPv6 addresses // use colon-separated syntax while IPv4 addresses use dotted decimal syntax. If // it decodes an IPv4 address, it writes the result to the first four bytes of -// |ipout| and returns four. If it decodes an IPv6 address, it writes the result -// to all 16 bytes of |ipout| and returns 16. Otherwise, it returns zero. +// `ipout` and returns four. If it decodes an IPv6 address, it writes the result +// to all 16 bytes of `ipout` and returns 16. Otherwise, it returns zero. int x509v3_a2i_ipadd(unsigned char ipout[16], const char *ipasc); -// A |BIT_STRING_BITNAME| is used to contain a list of bit names. +// A `BIT_STRING_BITNAME` is used to contain a list of bit names. typedef struct { int bitnum; const char *lname; const char *sname; } BIT_STRING_BITNAME; -// x509V3_add_value_asn1_string appends a |CONF_VALUE| with the specified name -// and value to |*extlist|. if |*extlist| is NULL, it sets |*extlist| to a -// newly-allocated |STACK_OF(CONF_VALUE)| first. It returns one on success and +// x509V3_add_value_asn1_string appends a `CONF_VALUE` with the specified name +// and value to `*extlist`. if `*extlist` is NULL, it sets `*extlist` to a +// newly-allocated `STACK_OF(CONF_VALUE)` first. It returns one on success and // zero on error. int x509V3_add_value_asn1_string(const char *name, const ASN1_STRING *value, STACK_OF(CONF_VALUE) **extlist); -// X509V3_NAME_from_section adds attributes to |nm| by interpreting the -// key/value pairs in |dn_sk|. It returns one on success and zero on error. -// |chtype|, which should be one of |MBSTRING_*| constants, determines the +// X509V3_NAME_from_section adds attributes to `nm` by interpreting the +// key/value pairs in `dn_sk`. It returns one on success and zero on error. +// `chtype`, which should be one of `MBSTRING_*` constants, determines the // character encoding used to interpret values. int X509V3_NAME_from_section(X509_NAME *nm, const STACK_OF(CONF_VALUE) *dn_sk, int chtype); -// X509V3_bool_from_string decodes |str| as a boolean. On success, it returns -// one and sets |*out_bool| to resulting value. Otherwise, it returns zero. +// X509V3_bool_from_string decodes `str` as a boolean. On success, it returns +// one and sets `*out_bool` to resulting value. Otherwise, it returns zero. int X509V3_bool_from_string(const char *str, ASN1_BOOLEAN *out_bool); -// X509V3_get_value_bool decodes |value| as a boolean. On success, it returns -// one and sets |*out_bool| to the resulting value. Otherwise, it returns zero. +// X509V3_get_value_bool decodes `value` as a boolean. On success, it returns +// one and sets `*out_bool` to the resulting value. Otherwise, it returns zero. int X509V3_get_value_bool(const CONF_VALUE *value, ASN1_BOOLEAN *out_bool); -// X509V3_get_value_int decodes |value| as an integer. On success, it returns -// one and sets |*aint| to the resulting value. Otherwise, it returns zero. If -// |*aint| was non-NULL at the start of the function, it frees the previous +// X509V3_get_value_int decodes `value` as an integer. On success, it returns +// one and sets `*aint` to the resulting value. Otherwise, it returns zero. If +// `*aint` was non-NULL at the start of the function, it frees the previous // value before writing a new one. int X509V3_get_value_int(const CONF_VALUE *value, ASN1_INTEGER **aint); -// X509V3_get_section behaves like |NCONF_get_section| but queries |ctx|'s +// X509V3_get_section behaves like `NCONF_get_section` but queries `ctx`'s // config database. const STACK_OF(CONF_VALUE) *X509V3_get_section(const X509V3_CTX *ctx, const char *section); -// X509V3_add_value appends a |CONF_VALUE| containing |name| and |value| to -// |*extlist|. It returns one on success and zero on error. If |*extlist| is -// NULL, it sets |*extlist| to a newly-allocated |STACK_OF(CONF_VALUE)| -// containing the result. Either |name| or |value| may be NULL to omit the +// X509V3_add_value appends a `CONF_VALUE` containing `name` and `value` to +// `*extlist`. It returns one on success and zero on error. If `*extlist` is +// NULL, it sets `*extlist` to a newly-allocated `STACK_OF(CONF_VALUE)` +// containing the result. Either `name` or `value` may be NULL to omit the // field. // -// On failure, if |*extlist| was NULL, |*extlist| will remain NULL when the +// On failure, if `*extlist` was NULL, `*extlist` will remain NULL when the // function returns. int X509V3_add_value(const char *name, const char *value, STACK_OF(CONF_VALUE) **extlist); -// X509V3_add_value_bool behaves like |X509V3_add_value| but stores the value -// "TRUE" if |asn1_bool| is non-zero and "FALSE" otherwise. +// X509V3_add_value_bool behaves like `X509V3_add_value` but stores the value +// "TRUE" if `asn1_bool` is non-zero and "FALSE" otherwise. int X509V3_add_value_bool(const char *name, int asn1_bool, STACK_OF(CONF_VALUE) **extlist); -// X509V3_add_value_bool behaves like |X509V3_add_value| but stores a string -// representation of |aint|. Note this string representation may be decimal or -// hexadecimal, depending on the size of |aint|. +// X509V3_add_value_bool behaves like `X509V3_add_value` but stores a string +// representation of `aint`. Note this string representation may be decimal or +// hexadecimal, depending on the size of `aint`. int X509V3_add_value_int(const char *name, const ASN1_INTEGER *aint, STACK_OF(CONF_VALUE) **extlist); @@ -580,7 +580,7 @@ ERR_add_error_data(6, "section:", (val)->section, ",name:", (val)->name, \ ",value:", (val)->value); -// GENERAL_NAME_cmp returns zero if |a| and |b| are equal and a non-zero +// GENERAL_NAME_cmp returns zero if `a` and `b` are equal and a non-zero // value otherwise. Note this function does not provide a comparison suitable // for sorting. // @@ -588,8 +588,8 @@ OPENSSL_EXPORT int GENERAL_NAME_cmp(const GENERAL_NAME *a, const GENERAL_NAME *b); -// X509_VERIFY_PARAM_lookup returns a pre-defined |X509_VERIFY_PARAM| named by -// |name|, or NULL if no such name is defined. +// X509_VERIFY_PARAM_lookup returns a pre-defined `X509_VERIFY_PARAM` named by +// `name`, or NULL if no such name is defined. const X509_VERIFY_PARAM *X509_VERIFY_PARAM_lookup(const char *name); GENERAL_NAME *v2i_GENERAL_NAME(const X509V3_EXT_METHOD *method, @@ -614,12 +614,12 @@ void x509_name_init(X509_NAME *name); void x509_name_cleanup(X509_NAME *name); -// x509_parse_name parses a DER-encoded, X.509 Name from |cbs| and writes the -// result to |*out|. It returns one on success and zero on error. +// x509_parse_name parses a DER-encoded, X.509 Name from `cbs` and writes the +// result to `*out`. It returns one on success and zero on error. int x509_parse_name(CBS *cbs, X509_NAME *out); -// x509_marshal_name marshals |in| as a DER-encoded, X.509 Name and writes the -// result to |out|. It returns one on success and zero on error. +// x509_marshal_name marshals `in` as a DER-encoded, X.509 Name and writes the +// result to `out`. It returns one on success and zero on error. int x509_marshal_name(CBB *out, const X509_NAME *in); const X509_NAME_CACHE *x509_name_get_cache(const X509_NAME *name); @@ -630,12 +630,12 @@ void x509_algor_init(X509_ALGOR *alg); void x509_algor_cleanup(X509_ALGOR *alg); -// x509_parse_algorithm parses a DER-encoded, AlgorithmIdentifier from |cbs| and -// writes the result to |*out|. It returns one on success and zero on error. +// x509_parse_algorithm parses a DER-encoded, AlgorithmIdentifier from `cbs` and +// writes the result to `*out`. It returns one on success and zero on error. int x509_parse_algorithm(CBS *cbs, X509_ALGOR *out); -// x509_marshal_algorithm marshals |in| as a DER-encoded, AlgorithmIdentifier -// and writes the result to |out|. It returns one on success and zero on error. +// x509_marshal_algorithm marshals `in` as a DER-encoded, AlgorithmIdentifier +// and writes the result to `out`. It returns one on success and zero on error. int x509_marshal_algorithm(CBB *out, const X509_ALGOR *in);