grpc 1.9.1 → 1.10.0.pre1

data/third_party/boringssl/include/openssl/poly1305.h

@@ -24,28 +24,28 @@ extern "C" {
 
 typedef uint8_t poly1305_state[512];
 
-/* CRYPTO_poly1305_init sets up |state| so that it can be used to calculate an
- * authentication tag with the one-time key |key|. Note that |key| is a
- * one-time key and therefore there is no `reset' method because that would
- * enable several messages to be authenticated with the same key. */
+// CRYPTO_poly1305_init sets up |state| so that it can be used to calculate an
+// authentication tag with the one-time key |key|. Note that |key| is a
+// one-time key and therefore there is no `reset' method because that would
+// enable several messages to be authenticated with the same key.
 OPENSSL_EXPORT void CRYPTO_poly1305_init(poly1305_state* state,
                                          const uint8_t key[32]);
 
-/* CRYPTO_poly1305_update processes |in_len| bytes from |in|. It can be called
- * zero or more times after poly1305_init. */
+// CRYPTO_poly1305_update processes |in_len| bytes from |in|. It can be called
+// zero or more times after poly1305_init.
 OPENSSL_EXPORT void CRYPTO_poly1305_update(poly1305_state* state,
                                            const uint8_t* in,
                                            size_t in_len);
 
-/* CRYPTO_poly1305_finish completes the poly1305 calculation and writes a 16
- * byte authentication tag to |mac|. The |mac| address must be 16-byte
- * aligned. */
+// CRYPTO_poly1305_finish completes the poly1305 calculation and writes a 16
+// byte authentication tag to |mac|. The |mac| address must be 16-byte
+// aligned.
 OPENSSL_EXPORT void CRYPTO_poly1305_finish(poly1305_state* state,
                                            uint8_t mac[16]);
 
 
 #if defined(__cplusplus)
-}  /* extern C */
+}  // extern C
 #endif
 
-#endif  /* OPENSSL_HEADER_POLY1305_H */
+#endif  // OPENSSL_HEADER_POLY1305_H

data/third_party/boringssl/include/openssl/pool.h

@@ -17,59 +17,63 @@
 
 #include <openssl/base.h>
 
+#include <openssl/stack.h>
+
 #if defined(__cplusplus)
 extern "C" {
 #endif
 
 
-/* Buffers and buffer pools.
- *
- * |CRYPTO_BUFFER|s are simply reference-counted blobs. A |CRYPTO_BUFFER_POOL|
- * is an intern table for |CRYPTO_BUFFER|s. This allows for a single copy of a
- * given blob to be kept in memory and referenced from multiple places. */
+// Buffers and buffer pools.
+//
+// |CRYPTO_BUFFER|s are simply reference-counted blobs. A |CRYPTO_BUFFER_POOL|
+// is an intern table for |CRYPTO_BUFFER|s. This allows for a single copy of a
+// given blob to be kept in memory and referenced from multiple places.
+
 
+DEFINE_STACK_OF(CRYPTO_BUFFER)
 
-/* CRYPTO_BUFFER_POOL_new returns a freshly allocated |CRYPTO_BUFFER_POOL| or
- * NULL on error. */
+// CRYPTO_BUFFER_POOL_new returns a freshly allocated |CRYPTO_BUFFER_POOL| or
+// NULL on error.
 OPENSSL_EXPORT CRYPTO_BUFFER_POOL* CRYPTO_BUFFER_POOL_new(void);
 
-/* CRYPTO_BUFFER_POOL_free frees |pool|, which must be empty. */
+// CRYPTO_BUFFER_POOL_free frees |pool|, which must be empty.
 OPENSSL_EXPORT void CRYPTO_BUFFER_POOL_free(CRYPTO_BUFFER_POOL *pool);
 
-/* CRYPTO_BUFFER_new returns a |CRYPTO_BUFFER| containing a copy of |data|, or
- * else NULL on error. If |pool| is not NULL then the returned value may be a
- * reference to a previously existing |CRYPTO_BUFFER| that contained the same
- * data. Otherwise, the returned, fresh |CRYPTO_BUFFER| will be added to the
- * pool. */
+// CRYPTO_BUFFER_new returns a |CRYPTO_BUFFER| containing a copy of |data|, or
+// else NULL on error. If |pool| is not NULL then the returned value may be a
+// reference to a previously existing |CRYPTO_BUFFER| that contained the same
+// data. Otherwise, the returned, fresh |CRYPTO_BUFFER| will be added to the
+// pool.
 OPENSSL_EXPORT CRYPTO_BUFFER *CRYPTO_BUFFER_new(const uint8_t *data, size_t len,
                                                 CRYPTO_BUFFER_POOL *pool);
 
-/* CRYPTO_BUFFER_new_from_CBS acts the same as |CRYPTO_BUFFER_new|. */
+// CRYPTO_BUFFER_new_from_CBS acts the same as |CRYPTO_BUFFER_new|.
 OPENSSL_EXPORT CRYPTO_BUFFER *CRYPTO_BUFFER_new_from_CBS(
     CBS *cbs, CRYPTO_BUFFER_POOL *pool);
 
-/* CRYPTO_BUFFER_free decrements the reference count of |buf|. If there are no
- * other references, or if the only remaining reference is from a pool, then
- * |buf| will be freed. */
+// CRYPTO_BUFFER_free decrements the reference count of |buf|. If there are no
+// other references, or if the only remaining reference is from a pool, then
+// |buf| will be freed.
 OPENSSL_EXPORT void CRYPTO_BUFFER_free(CRYPTO_BUFFER *buf);
 
-/* CRYPTO_BUFFER_up_ref increments the reference count of |buf| and returns
- * one. */
+// CRYPTO_BUFFER_up_ref increments the reference count of |buf| and returns
+// one.
 OPENSSL_EXPORT int CRYPTO_BUFFER_up_ref(CRYPTO_BUFFER *buf);
 
-/* CRYPTO_BUFFER_data returns a pointer to the data contained in |buf|. */
+// CRYPTO_BUFFER_data returns a pointer to the data contained in |buf|.
 OPENSSL_EXPORT const uint8_t *CRYPTO_BUFFER_data(const CRYPTO_BUFFER *buf);
 
-/* CRYPTO_BUFFER_len returns the length, in bytes, of the data contained in
- * |buf|. */
+// CRYPTO_BUFFER_len returns the length, in bytes, of the data contained in
+// |buf|.
 OPENSSL_EXPORT size_t CRYPTO_BUFFER_len(const CRYPTO_BUFFER *buf);
 
-/* CRYPTO_BUFFER_init_CBS initialises |out| to point at the data from |buf|. */
+// CRYPTO_BUFFER_init_CBS initialises |out| to point at the data from |buf|.
 OPENSSL_EXPORT void CRYPTO_BUFFER_init_CBS(const CRYPTO_BUFFER *buf, CBS *out);
 
 
 #if defined(__cplusplus)
-}  /* extern C */
+}  // extern C
 
 extern "C++" {
 
@@ -80,7 +84,7 @@ BORINGSSL_MAKE_DELETER(CRYPTO_BUFFER, CRYPTO_BUFFER_free)
 
 }  // namespace bssl
 
-}  /* extern C++ */
+}  // extern C++
 
 #endif
 

data/third_party/boringssl/include/openssl/rand.h

@@ -22,83 +22,83 @@ extern "C" {
 #endif
 
 
-/* Random number generation. */
+// Random number generation.
 
 
-/* RAND_bytes writes |len| bytes of random data to |buf| and returns one. */
+// RAND_bytes writes |len| bytes of random data to |buf| and returns one.
 OPENSSL_EXPORT int RAND_bytes(uint8_t *buf, size_t len);
 
-/* RAND_cleanup frees any resources used by the RNG. This is not safe if other
- * threads might still be calling |RAND_bytes|. */
+// RAND_cleanup frees any resources used by the RNG. This is not safe if other
+// threads might still be calling |RAND_bytes|.
 OPENSSL_EXPORT void RAND_cleanup(void);
 
 
-/* Obscure functions. */
+// Obscure functions.
 
 #if !defined(OPENSSL_WINDOWS)
-/* RAND_set_urandom_fd causes the module to use a copy of |fd| for system
- * randomness rather opening /dev/urandom internally. The caller retains
- * ownership of |fd| and is at liberty to close it at any time. This is useful
- * if, due to a sandbox, /dev/urandom isn't available. If used, it must be
- * called before the first call to |RAND_bytes|, and it is mutually exclusive
- * with |RAND_enable_fork_unsafe_buffering|.
- *
- * |RAND_set_urandom_fd| does not buffer any entropy, so it is safe to call
- * |fork| at any time after calling |RAND_set_urandom_fd|. */
+// RAND_set_urandom_fd causes the module to use a copy of |fd| for system
+// randomness rather opening /dev/urandom internally. The caller retains
+// ownership of |fd| and is at liberty to close it at any time. This is useful
+// if, due to a sandbox, /dev/urandom isn't available. If used, it must be
+// called before the first call to |RAND_bytes|, and it is mutually exclusive
+// with |RAND_enable_fork_unsafe_buffering|.
+//
+// |RAND_set_urandom_fd| does not buffer any entropy, so it is safe to call
+// |fork| at any time after calling |RAND_set_urandom_fd|.
 OPENSSL_EXPORT void RAND_set_urandom_fd(int fd);
 
-/* RAND_enable_fork_unsafe_buffering enables efficient buffered reading of
- * /dev/urandom. It adds an overhead of a few KB of memory per thread. It must
- * be called before the first call to |RAND_bytes| and it is mutually exclusive
- * with calls to |RAND_set_urandom_fd|.
- *
- * If |fd| is non-negative then a copy of |fd| will be used rather than opening
- * /dev/urandom internally. Like |RAND_set_urandom_fd|, the caller retains
- * ownership of |fd|. If |fd| is negative then /dev/urandom will be opened and
- * any error from open(2) crashes the address space.
- *
- * It has an unusual name because the buffer is unsafe across calls to |fork|.
- * Hence, this function should never be called by libraries. */
+// RAND_enable_fork_unsafe_buffering enables efficient buffered reading of
+// /dev/urandom. It adds an overhead of a few KB of memory per thread. It must
+// be called before the first call to |RAND_bytes| and it is mutually exclusive
+// with calls to |RAND_set_urandom_fd|.
+//
+// If |fd| is non-negative then a copy of |fd| will be used rather than opening
+// /dev/urandom internally. Like |RAND_set_urandom_fd|, the caller retains
+// ownership of |fd|. If |fd| is negative then /dev/urandom will be opened and
+// any error from open(2) crashes the address space.
+//
+// It has an unusual name because the buffer is unsafe across calls to |fork|.
+// Hence, this function should never be called by libraries.
 OPENSSL_EXPORT void RAND_enable_fork_unsafe_buffering(int fd);
 #endif
 
 #if defined(BORINGSSL_UNSAFE_DETERMINISTIC_MODE)
-/* RAND_reset_for_fuzzing resets the fuzzer-only deterministic RNG. This
- * function is only defined in the fuzzer-only build configuration. */
+// RAND_reset_for_fuzzing resets the fuzzer-only deterministic RNG. This
+// function is only defined in the fuzzer-only build configuration.
 OPENSSL_EXPORT void RAND_reset_for_fuzzing(void);
 #endif
 
 
-/* Deprecated functions */
+// Deprecated functions
 
-/* RAND_pseudo_bytes is a wrapper around |RAND_bytes|. */
+// RAND_pseudo_bytes is a wrapper around |RAND_bytes|.
 OPENSSL_EXPORT int RAND_pseudo_bytes(uint8_t *buf, size_t len);
 
-/* RAND_seed reads a single byte of random data to ensure that any file
- * descriptors etc are opened. */
+// RAND_seed reads a single byte of random data to ensure that any file
+// descriptors etc are opened.
 OPENSSL_EXPORT void RAND_seed(const void *buf, int num);
 
-/* RAND_load_file returns a nonnegative number. */
+// RAND_load_file returns a nonnegative number.
 OPENSSL_EXPORT int RAND_load_file(const char *path, long num);
 
-/* RAND_file_name returns NULL. */
+// RAND_file_name returns NULL.
 OPENSSL_EXPORT const char *RAND_file_name(char *buf, size_t num);
 
-/* RAND_add does nothing. */
+// RAND_add does nothing.
 OPENSSL_EXPORT void RAND_add(const void *buf, int num, double entropy);
 
-/* RAND_egd returns 255. */
+// RAND_egd returns 255.
 OPENSSL_EXPORT int RAND_egd(const char *);
 
-/* RAND_poll returns one. */
+// RAND_poll returns one.
 OPENSSL_EXPORT int RAND_poll(void);
 
-/* RAND_status returns one. */
+// RAND_status returns one.
 OPENSSL_EXPORT int RAND_status(void);
 
-/* rand_meth_st is typedefed to |RAND_METHOD| in base.h. It isn't used; it
- * exists only to be the return type of |RAND_SSLeay|. It's
- * external so that variables of this type can be initialized. */
+// rand_meth_st is typedefed to |RAND_METHOD| in base.h. It isn't used; it
+// exists only to be the return type of |RAND_SSLeay|. It's
+// external so that variables of this type can be initialized.
 struct rand_meth_st {
   void (*seed) (const void *buf, int num);
   int (*bytes) (uint8_t *buf, size_t num);
@@ -108,15 +108,18 @@ struct rand_meth_st {
   int (*status) (void);
 };
 
-/* RAND_SSLeay returns a pointer to a dummy |RAND_METHOD|. */
+// RAND_SSLeay returns a pointer to a dummy |RAND_METHOD|.
 OPENSSL_EXPORT RAND_METHOD *RAND_SSLeay(void);
 
-/* RAND_set_rand_method does nothing. */
+// RAND_get_rand_method returns |RAND_SSLeay()|.
+OPENSSL_EXPORT const RAND_METHOD *RAND_get_rand_method(void);
+
+// RAND_set_rand_method does nothing.
 OPENSSL_EXPORT void RAND_set_rand_method(const RAND_METHOD *);
 
 
 #if defined(__cplusplus)
-}  /* extern C */
+}  // extern C
 #endif
 
-#endif  /* OPENSSL_HEADER_RAND_H */
+#endif  // OPENSSL_HEADER_RAND_H

data/third_party/boringssl/include/openssl/rc4.h

@@ -64,7 +64,7 @@ extern "C" {
 #endif
 
 
-/* RC4. */
+// RC4.
 
 
 struct rc4_key_st {
@@ -72,25 +72,25 @@ struct rc4_key_st {
   uint32_t data[256];
 } /* RC4_KEY */;
 
-/* RC4_set_key performs an RC4 key schedule and initialises |rc4key| with |len|
- * bytes of key material from |key|. */
+// RC4_set_key performs an RC4 key schedule and initialises |rc4key| with |len|
+// bytes of key material from |key|.
 OPENSSL_EXPORT void RC4_set_key(RC4_KEY *rc4key, unsigned len,
                                 const uint8_t *key);
 
-/* RC4 encrypts (or decrypts, it's the same with RC4) |len| bytes from |in| to
- * |out|. */
+// RC4 encrypts (or decrypts, it's the same with RC4) |len| bytes from |in| to
+// |out|.
 OPENSSL_EXPORT void RC4(RC4_KEY *key, size_t len, const uint8_t *in,
                         uint8_t *out);
 
 
-/* Deprecated functions. */
+// Deprecated functions.
 
-/* RC4_options returns the string "rc4(ptr,int)". */
+// RC4_options returns the string "rc4(ptr,int)".
 OPENSSL_EXPORT const char *RC4_options(void);
 
 
 #if defined(__cplusplus)
-}  /* extern C */
+}  // extern C
 #endif
 
-#endif  /* OPENSSL_HEADER_RC4_H */
+#endif  // OPENSSL_HEADER_RC4_H

data/third_party/boringssl/include/openssl/ripemd.h

@@ -75,33 +75,33 @@ struct RIPEMD160state_st {
   unsigned num;
 };
 
-/* RIPEMD160_Init initialises |ctx| and returns one. */
+// RIPEMD160_Init initialises |ctx| and returns one.
 OPENSSL_EXPORT int RIPEMD160_Init(RIPEMD160_CTX *ctx);
 
-/* RIPEMD160_Update adds |len| bytes from |data| to |ctx| and returns one. */
+// RIPEMD160_Update adds |len| bytes from |data| to |ctx| and returns one.
 OPENSSL_EXPORT int RIPEMD160_Update(RIPEMD160_CTX *ctx, const void *data,
                                    size_t len);
 
-/* RIPEMD160_Final adds the final padding to |ctx| and writes the resulting
- * digest to |md|, which must have at least |RIPEMD160_DIGEST_LENGTH| bytes of
- * space. It returns one. */
+// RIPEMD160_Final adds the final padding to |ctx| and writes the resulting
+// digest to |md|, which must have at least |RIPEMD160_DIGEST_LENGTH| bytes of
+// space. It returns one.
 OPENSSL_EXPORT int RIPEMD160_Final(uint8_t *md, RIPEMD160_CTX *ctx);
 
-/* RIPEMD160 writes the digest of |len| bytes from |data| to |out| and returns
- * |out|. There must be at least |RIPEMD160_DIGEST_LENGTH| bytes of space in
- * |out|. */
+// RIPEMD160 writes the digest of |len| bytes from |data| to |out| and returns
+// |out|. There must be at least |RIPEMD160_DIGEST_LENGTH| bytes of space in
+// |out|.
 OPENSSL_EXPORT uint8_t *RIPEMD160(const uint8_t *data, size_t len,
                                   uint8_t *out);
 
-/* RIPEMD160_Transform is a low-level function that performs a single,
- * RIPEMD160 block transformation using the state from |ctx| and 64 bytes from
- * |block|. */
+// RIPEMD160_Transform is a low-level function that performs a single,
+// RIPEMD160 block transformation using the state from |ctx| and 64 bytes from
+// |block|.
 OPENSSL_EXPORT void RIPEMD160_Transform(RIPEMD160_CTX *ctx,
                                         const uint8_t *block);
 
 
 #if defined(__cplusplus)
-}  /* extern C */
+}  // extern C
 #endif
 
-#endif  /* OPENSSL_HEADER_RIPEMD_H */
+#endif  // OPENSSL_HEADER_RIPEMD_H

data/third_party/boringssl/include/openssl/rsa.h

@@ -68,462 +68,522 @@ extern "C" {
 #endif
 
 
-/* rsa.h contains functions for handling encryption and signature using RSA. */
+// rsa.h contains functions for handling encryption and signature using RSA.
 
 
-/* Allocation and destruction. */
+// Allocation and destruction.
 
-/* RSA_new returns a new, empty RSA object or NULL on error. */
+// RSA_new returns a new, empty RSA object or NULL on error.
 OPENSSL_EXPORT RSA *RSA_new(void);
 
-/* RSA_new_method acts the same as |RSA_new| but takes an explicit |ENGINE|. */
+// RSA_new_method acts the same as |RSA_new| but takes an explicit |ENGINE|.
 OPENSSL_EXPORT RSA *RSA_new_method(const ENGINE *engine);
 
-/* RSA_free decrements the reference count of |rsa| and frees it if the
- * reference count drops to zero. */
+// RSA_free decrements the reference count of |rsa| and frees it if the
+// reference count drops to zero.
 OPENSSL_EXPORT void RSA_free(RSA *rsa);
 
-/* RSA_up_ref increments the reference count of |rsa| and returns one. */
+// RSA_up_ref increments the reference count of |rsa| and returns one.
 OPENSSL_EXPORT int RSA_up_ref(RSA *rsa);
 
 
-/* Properties. */
+// Properties.
 
-/* RSA_get0_key sets |*out_n|, |*out_e|, and |*out_d|, if non-NULL, to |rsa|'s
- * modulus, public exponent, and private exponent, respectively. If |rsa| is a
- * public key, the private exponent will be set to NULL. */
+// RSA_get0_key sets |*out_n|, |*out_e|, and |*out_d|, if non-NULL, to |rsa|'s
+// modulus, public exponent, and private exponent, respectively. If |rsa| is a
+// public key, the private exponent will be set to NULL.
 OPENSSL_EXPORT void RSA_get0_key(const RSA *rsa, const BIGNUM **out_n,
                                  const BIGNUM **out_e, const BIGNUM **out_d);
 
-/* RSA_get0_factors sets |*out_p| and |*out_q|, if non-NULL, to |rsa|'s prime
- * factors. If |rsa| is a public key, they will be set to NULL. If |rsa| is a
- * multi-prime key, only the first two prime factors will be reported. */
+// RSA_get0_factors sets |*out_p| and |*out_q|, if non-NULL, to |rsa|'s prime
+// factors. If |rsa| is a public key, they will be set to NULL.
 OPENSSL_EXPORT void RSA_get0_factors(const RSA *rsa, const BIGNUM **out_p,
                                      const BIGNUM **out_q);
 
-/* RSA_get0_crt_params sets |*out_dmp1|, |*out_dmq1|, and |*out_iqmp|, if
- * non-NULL, to |rsa|'s CRT parameters. These are d (mod p-1), d (mod q-1) and
- * q^-1 (mod p), respectively. If |rsa| is a public key, each parameter will be
- * set to NULL. If |rsa| is a multi-prime key, only the CRT parameters for the
- * first two primes will be reported. */
+// RSA_get0_crt_params sets |*out_dmp1|, |*out_dmq1|, and |*out_iqmp|, if
+// non-NULL, to |rsa|'s CRT parameters. These are d (mod p-1), d (mod q-1) and
+// q^-1 (mod p), respectively. If |rsa| is a public key, each parameter will be
+// set to NULL.
 OPENSSL_EXPORT void RSA_get0_crt_params(const RSA *rsa, const BIGNUM **out_dmp1,
                                         const BIGNUM **out_dmq1,
                                         const BIGNUM **out_iqmp);
 
-
-/* Key generation. */
-
-/* RSA_generate_key_ex generates a new RSA key where the modulus has size
- * |bits| and the public exponent is |e|. If unsure, |RSA_F4| is a good value
- * for |e|. If |cb| is not NULL then it is called during the key generation
- * process. In addition to the calls documented for |BN_generate_prime_ex|, it
- * is called with event=2 when the n'th prime is rejected as unsuitable and
- * with event=3 when a suitable value for |p| is found.
- *
- * It returns one on success or zero on error. */
+// RSA_set0_key sets |rsa|'s modulus, public exponent, and private exponent to
+// |n|, |e|, and |d| respectively, if non-NULL. On success, it takes ownership
+// of each argument and returns one. Otherwise, it returns zero.
+//
+// |d| may be NULL, but |n| and |e| must either be non-NULL or already
+// configured on |rsa|.
+OPENSSL_EXPORT int RSA_set0_key(RSA *rsa, BIGNUM *n, BIGNUM *e, BIGNUM *d);
+
+// RSA_set0_factors sets |rsa|'s prime factors to |p| and |q|, if non-NULL, and
+// takes ownership of them. On success, it takes ownership of each argument and
+// returns one. Otherwise, it returns zero.
+//
+// Each argument must either be non-NULL or already configured on |rsa|.
+OPENSSL_EXPORT int RSA_set0_factors(RSA *rsa, BIGNUM *p, BIGNUM *q);
+
+// RSA_set0_crt_params sets |rsa|'s CRT parameters to |dmp1|, |dmq1|, and
+// |iqmp|, if non-NULL, and takes ownership of them. On success, it takes
+// ownership of its parameters and returns one. Otherwise, it returns zero.
+//
+// Each argument must either be non-NULL or already configured on |rsa|.
+OPENSSL_EXPORT int RSA_set0_crt_params(RSA *rsa, BIGNUM *dmp1, BIGNUM *dmq1,
+                                       BIGNUM *iqmp);
+
+
+// Key generation.
+
+// RSA_generate_key_ex generates a new RSA key where the modulus has size
+// |bits| and the public exponent is |e|. If unsure, |RSA_F4| is a good value
+// for |e|. If |cb| is not NULL then it is called during the key generation
+// process. In addition to the calls documented for |BN_generate_prime_ex|, it
+// is called with event=2 when the n'th prime is rejected as unsuitable and
+// with event=3 when a suitable value for |p| is found.
+//
+// It returns one on success or zero on error.
 OPENSSL_EXPORT int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e,
                                        BN_GENCB *cb);
 
-/* RSA_generate_multi_prime_key acts like |RSA_generate_key_ex| but can
- * generate an RSA private key with more than two primes. */
-OPENSSL_EXPORT int RSA_generate_multi_prime_key(RSA *rsa, int bits,
-                                                int num_primes, BIGNUM *e,
-                                                BN_GENCB *cb);
+// RSA_generate_key_fips behaves like |RSA_generate_key_ex| but performs
+// additional checks for FIPS compliance. The public exponent is always 65537
+// and |bits| must be either 2048 or 3072.
+OPENSSL_EXPORT int RSA_generate_key_fips(RSA *rsa, int bits, BN_GENCB *cb);
 
 
-/* Encryption / Decryption */
+// Encryption / Decryption
 
-/* Padding types for encryption. */
+// Padding types for encryption.
 #define RSA_PKCS1_PADDING 1
 #define RSA_NO_PADDING 3
 #define RSA_PKCS1_OAEP_PADDING 4
-/* RSA_PKCS1_PSS_PADDING can only be used via the EVP interface. */
+// RSA_PKCS1_PSS_PADDING can only be used via the EVP interface.
 #define RSA_PKCS1_PSS_PADDING 6
 
-/* RSA_encrypt encrypts |in_len| bytes from |in| to the public key from |rsa|
- * and writes, at most, |max_out| bytes of encrypted data to |out|. The
- * |max_out| argument must be, at least, |RSA_size| in order to ensure success.
- *
- * It returns 1 on success or zero on error.
- *
- * The |padding| argument must be one of the |RSA_*_PADDING| values. If in
- * doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols but
- * |RSA_PKCS1_PADDING| is most common. */
+// RSA_encrypt encrypts |in_len| bytes from |in| to the public key from |rsa|
+// and writes, at most, |max_out| bytes of encrypted data to |out|. The
+// |max_out| argument must be, at least, |RSA_size| in order to ensure success.
+//
+// It returns 1 on success or zero on error.
+//
+// The |padding| argument must be one of the |RSA_*_PADDING| values. If in
+// doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols but
+// |RSA_PKCS1_PADDING| is most common.
 OPENSSL_EXPORT int RSA_encrypt(RSA *rsa, size_t *out_len, uint8_t *out,
                                size_t max_out, const uint8_t *in, size_t in_len,
                                int padding);
 
-/* RSA_decrypt decrypts |in_len| bytes from |in| with the private key from
- * |rsa| and writes, at most, |max_out| bytes of plaintext to |out|. The
- * |max_out| argument must be, at least, |RSA_size| in order to ensure success.
- *
- * It returns 1 on success or zero on error.
- *
- * The |padding| argument must be one of the |RSA_*_PADDING| values. If in
- * doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols.
- *
- * Passing |RSA_PKCS1_PADDING| into this function is deprecated and insecure. If
- * implementing a protocol using RSAES-PKCS1-V1_5, use |RSA_NO_PADDING| and then
- * check padding in constant-time combined with a swap to a random session key
- * or other mitigation. See "Chosen Ciphertext Attacks Against Protocols Based
- * on the RSA Encryption Standard PKCS #1", Daniel Bleichenbacher, Advances in
- * Cryptology (Crypto '98). */
+// RSA_decrypt decrypts |in_len| bytes from |in| with the private key from
+// |rsa| and writes, at most, |max_out| bytes of plaintext to |out|. The
+// |max_out| argument must be, at least, |RSA_size| in order to ensure success.
+//
+// It returns 1 on success or zero on error.
+//
+// The |padding| argument must be one of the |RSA_*_PADDING| values. If in
+// doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols.
+//
+// Passing |RSA_PKCS1_PADDING| into this function is deprecated and insecure. If
+// implementing a protocol using RSAES-PKCS1-V1_5, use |RSA_NO_PADDING| and then
+// check padding in constant-time combined with a swap to a random session key
+// or other mitigation. See "Chosen Ciphertext Attacks Against Protocols Based
+// on the RSA Encryption Standard PKCS #1", Daniel Bleichenbacher, Advances in
+// Cryptology (Crypto '98).
 OPENSSL_EXPORT int RSA_decrypt(RSA *rsa, size_t *out_len, uint8_t *out,
                                size_t max_out, const uint8_t *in, size_t in_len,
                                int padding);
 
-/* RSA_public_encrypt encrypts |flen| bytes from |from| to the public key in
- * |rsa| and writes the encrypted data to |to|. The |to| buffer must have at
- * least |RSA_size| bytes of space. It returns the number of bytes written, or
- * -1 on error. The |padding| argument must be one of the |RSA_*_PADDING|
- * values. If in doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols but
- * |RSA_PKCS1_PADDING| is most common.
- *
- * WARNING: this function is dangerous because it breaks the usual return value
- * convention. Use |RSA_encrypt| instead. */
+// RSA_public_encrypt encrypts |flen| bytes from |from| to the public key in
+// |rsa| and writes the encrypted data to |to|. The |to| buffer must have at
+// least |RSA_size| bytes of space. It returns the number of bytes written, or
+// -1 on error. The |padding| argument must be one of the |RSA_*_PADDING|
+// values. If in doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols but
+// |RSA_PKCS1_PADDING| is most common.
+//
+// WARNING: this function is dangerous because it breaks the usual return value
+// convention. Use |RSA_encrypt| instead.
 OPENSSL_EXPORT int RSA_public_encrypt(size_t flen, const uint8_t *from,
                                       uint8_t *to, RSA *rsa, int padding);
 
-/* RSA_private_decrypt decrypts |flen| bytes from |from| with the public key in
- * |rsa| and writes the plaintext to |to|. The |to| buffer must have at least
- * |RSA_size| bytes of space. It returns the number of bytes written, or -1 on
- * error. The |padding| argument must be one of the |RSA_*_PADDING| values. If
- * in doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols. Passing
- * |RSA_PKCS1_PADDING| into this function is deprecated and insecure. See
- * |RSA_decrypt|.
- *
- * WARNING: this function is dangerous because it breaks the usual return value
- * convention. Use |RSA_decrypt| instead. */
+// RSA_private_decrypt decrypts |flen| bytes from |from| with the public key in
+// |rsa| and writes the plaintext to |to|. The |to| buffer must have at least
+// |RSA_size| bytes of space. It returns the number of bytes written, or -1 on
+// error. The |padding| argument must be one of the |RSA_*_PADDING| values. If
+// in doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols. Passing
+// |RSA_PKCS1_PADDING| into this function is deprecated and insecure. See
+// |RSA_decrypt|.
+//
+// WARNING: this function is dangerous because it breaks the usual return value
+// convention. Use |RSA_decrypt| instead.
 OPENSSL_EXPORT int RSA_private_decrypt(size_t flen, const uint8_t *from,
                                        uint8_t *to, RSA *rsa, int padding);
 
 
-/* Signing / Verification */
+// Signing / Verification
 
-/* RSA_sign signs |in_len| bytes of digest from |in| with |rsa| using
- * RSASSA-PKCS1-v1_5. It writes, at most, |RSA_size(rsa)| bytes to |out|. On
- * successful return, the actual number of bytes written is written to
- * |*out_len|.
- *
- * The |hash_nid| argument identifies the hash function used to calculate |in|
- * and is embedded in the resulting signature. For example, it might be
- * |NID_sha256|.
- *
- * It returns 1 on success and zero on error. */
+// RSA_sign signs |in_len| bytes of digest from |in| with |rsa| using
+// RSASSA-PKCS1-v1_5. It writes, at most, |RSA_size(rsa)| bytes to |out|. On
+// successful return, the actual number of bytes written is written to
+// |*out_len|.
+//
+// The |hash_nid| argument identifies the hash function used to calculate |in|
+// and is embedded in the resulting signature. For example, it might be
+// |NID_sha256|.
+//
+// It returns 1 on success and zero on error.
 OPENSSL_EXPORT int RSA_sign(int hash_nid, const uint8_t *in,
                             unsigned int in_len, uint8_t *out,
                             unsigned int *out_len, RSA *rsa);
 
-/* RSA_sign_raw signs |in_len| bytes from |in| with the public key from |rsa|
- * and writes, at most, |max_out| bytes of signature data to |out|. The
- * |max_out| argument must be, at least, |RSA_size| in order to ensure success.
- *
- * It returns 1 on success or zero on error.
- *
- * The |padding| argument must be one of the |RSA_*_PADDING| values. If in
- * doubt, |RSA_PKCS1_PADDING| is the most common but |RSA_PKCS1_PSS_PADDING|
- * (via the |EVP_PKEY| interface) is preferred for new protocols. */
+// RSA_sign_pss_mgf1 signs |in_len| bytes from |in| with the public key from
+// |rsa| using RSASSA-PSS with MGF1 as the mask generation function. It writes,
+// at most, |max_out| bytes of signature data to |out|. The |max_out| argument
+// must be, at least, |RSA_size| in order to ensure success. It returns 1 on
+// success or zero on error.
+//
+// The |md| and |mgf1_md| arguments identify the hash used to calculate |msg|
+// and the MGF1 hash, respectively. If |mgf1_md| is NULL, |md| is
+// used.
+//
+// |salt_len| specifies the expected salt length in bytes. If |salt_len| is -1,
+// then the salt length is the same as the hash length. If -2, then the salt
+// length is maximal given the size of |rsa|. If unsure, use -1.
+OPENSSL_EXPORT int RSA_sign_pss_mgf1(RSA *rsa, size_t *out_len, uint8_t *out,
+                                     size_t max_out, const uint8_t *in,
+                                     size_t in_len, const EVP_MD *md,
+                                     const EVP_MD *mgf1_md, int salt_len);
+
+// RSA_sign_raw signs |in_len| bytes from |in| with the public key from |rsa|
+// and writes, at most, |max_out| bytes of signature data to |out|. The
+// |max_out| argument must be, at least, |RSA_size| in order to ensure success.
+//
+// It returns 1 on success or zero on error.
+//
+// The |padding| argument must be one of the |RSA_*_PADDING| values. If in
+// doubt, |RSA_PKCS1_PADDING| is the most common but |RSA_PKCS1_PSS_PADDING|
+// (via the |EVP_PKEY| interface) is preferred for new protocols.
 OPENSSL_EXPORT int RSA_sign_raw(RSA *rsa, size_t *out_len, uint8_t *out,
                                 size_t max_out, const uint8_t *in,
                                 size_t in_len, int padding);
 
-/* RSA_verify verifies that |sig_len| bytes from |sig| are a valid,
- * RSASSA-PKCS1-v1_5 signature of |msg_len| bytes at |msg| by |rsa|.
- *
- * The |hash_nid| argument identifies the hash function used to calculate |in|
- * and is embedded in the resulting signature in order to prevent hash
- * confusion attacks. For example, it might be |NID_sha256|.
- *
- * It returns one if the signature is valid and zero otherwise.
- *
- * WARNING: this differs from the original, OpenSSL function which additionally
- * returned -1 on error. */
+// RSA_verify verifies that |sig_len| bytes from |sig| are a valid,
+// RSASSA-PKCS1-v1_5 signature of |msg_len| bytes at |msg| by |rsa|.
+//
+// The |hash_nid| argument identifies the hash function used to calculate |msg|
+// and is embedded in the resulting signature in order to prevent hash
+// confusion attacks. For example, it might be |NID_sha256|.
+//
+// It returns one if the signature is valid and zero otherwise.
+//
+// WARNING: this differs from the original, OpenSSL function which additionally
+// returned -1 on error.
 OPENSSL_EXPORT int RSA_verify(int hash_nid, const uint8_t *msg, size_t msg_len,
                               const uint8_t *sig, size_t sig_len, RSA *rsa);
 
-/* RSA_verify_raw verifies |in_len| bytes of signature from |in| using the
- * public key from |rsa| and writes, at most, |max_out| bytes of plaintext to
- * |out|. The |max_out| argument must be, at least, |RSA_size| in order to
- * ensure success.
- *
- * It returns 1 on success or zero on error.
- *
- * The |padding| argument must be one of the |RSA_*_PADDING| values. If in
- * doubt, |RSA_PKCS1_PADDING| is the most common but |RSA_PKCS1_PSS_PADDING|
- * (via the |EVP_PKEY| interface) is preferred for new protocols. */
+// RSA_verify_pss_mgf1 verifies that |sig_len| bytes from |sig| are a valid,
+// RSASSA-PSS signature of |msg_len| bytes at |msg| by |rsa|. It returns one if
+// the signature is valid and zero otherwise. MGF1 is used as the mask
+// generation function.
+//
+// The |md| and |mgf1_md| arguments identify the hash used to calculate |msg|
+// and the MGF1 hash, respectively. If |mgf1_md| is NULL, |md| is
+// used. |salt_len| specifies the expected salt length in bytes.
+//
+// If |salt_len| is -1, then the salt length is the same as the hash length. If
+// -2, then the salt length is recovered and all values accepted. If unsure, use
+// -1.
+OPENSSL_EXPORT int RSA_verify_pss_mgf1(RSA *rsa, const uint8_t *msg,
+                                       size_t msg_len, const EVP_MD *md,
+                                       const EVP_MD *mgf1_md, int salt_len,
+                                       const uint8_t *sig, size_t sig_len);
+
+// RSA_verify_raw verifies |in_len| bytes of signature from |in| using the
+// public key from |rsa| and writes, at most, |max_out| bytes of plaintext to
+// |out|. The |max_out| argument must be, at least, |RSA_size| in order to
+// ensure success.
+//
+// It returns 1 on success or zero on error.
+//
+// The |padding| argument must be one of the |RSA_*_PADDING| values. If in
+// doubt, |RSA_PKCS1_PADDING| is the most common but |RSA_PKCS1_PSS_PADDING|
+// (via the |EVP_PKEY| interface) is preferred for new protocols.
 OPENSSL_EXPORT int RSA_verify_raw(RSA *rsa, size_t *out_len, uint8_t *out,
                                   size_t max_out, const uint8_t *in,
                                   size_t in_len, int padding);
 
-/* RSA_private_encrypt encrypts |flen| bytes from |from| with the private key in
- * |rsa| and writes the encrypted data to |to|. The |to| buffer must have at
- * least |RSA_size| bytes of space. It returns the number of bytes written, or
- * -1 on error. The |padding| argument must be one of the |RSA_*_PADDING|
- * values. If in doubt, |RSA_PKCS1_PADDING| is the most common but
- * |RSA_PKCS1_PSS_PADDING| (via the |EVP_PKEY| interface) is preferred for new
- * protocols.
- *
- * WARNING: this function is dangerous because it breaks the usual return value
- * convention. Use |RSA_sign_raw| instead. */
+// RSA_private_encrypt encrypts |flen| bytes from |from| with the private key in
+// |rsa| and writes the encrypted data to |to|. The |to| buffer must have at
+// least |RSA_size| bytes of space. It returns the number of bytes written, or
+// -1 on error. The |padding| argument must be one of the |RSA_*_PADDING|
+// values. If in doubt, |RSA_PKCS1_PADDING| is the most common but
+// |RSA_PKCS1_PSS_PADDING| (via the |EVP_PKEY| interface) is preferred for new
+// protocols.
+//
+// WARNING: this function is dangerous because it breaks the usual return value
+// convention. Use |RSA_sign_raw| instead.
 OPENSSL_EXPORT int RSA_private_encrypt(size_t flen, const uint8_t *from,
                                        uint8_t *to, RSA *rsa, int padding);
 
-/* RSA_public_decrypt verifies |flen| bytes of signature from |from| using the
- * public key in |rsa| and writes the plaintext to |to|. The |to| buffer must
- * have at least |RSA_size| bytes of space. It returns the number of bytes
- * written, or -1 on error. The |padding| argument must be one of the
- * |RSA_*_PADDING| values. If in doubt, |RSA_PKCS1_PADDING| is the most common
- * but |RSA_PKCS1_PSS_PADDING| (via the |EVP_PKEY| interface) is preferred for
- * new protocols.
- *
- * WARNING: this function is dangerous because it breaks the usual return value
- * convention. Use |RSA_verify_raw| instead. */
+// RSA_public_decrypt verifies |flen| bytes of signature from |from| using the
+// public key in |rsa| and writes the plaintext to |to|. The |to| buffer must
+// have at least |RSA_size| bytes of space. It returns the number of bytes
+// written, or -1 on error. The |padding| argument must be one of the
+// |RSA_*_PADDING| values. If in doubt, |RSA_PKCS1_PADDING| is the most common
+// but |RSA_PKCS1_PSS_PADDING| (via the |EVP_PKEY| interface) is preferred for
+// new protocols.
+//
+// WARNING: this function is dangerous because it breaks the usual return value
+// convention. Use |RSA_verify_raw| instead.
 OPENSSL_EXPORT int RSA_public_decrypt(size_t flen, const uint8_t *from,
                                       uint8_t *to, RSA *rsa, int padding);
 
 
-/* Utility functions. */
+// Utility functions.
 
-/* RSA_size returns the number of bytes in the modulus, which is also the size
- * of a signature or encrypted value using |rsa|. */
+// RSA_size returns the number of bytes in the modulus, which is also the size
+// of a signature or encrypted value using |rsa|.
 OPENSSL_EXPORT unsigned RSA_size(const RSA *rsa);
 
-/* RSA_is_opaque returns one if |rsa| is opaque and doesn't expose its key
- * material. Otherwise it returns zero. */
+// RSA_is_opaque returns one if |rsa| is opaque and doesn't expose its key
+// material. Otherwise it returns zero.
 OPENSSL_EXPORT int RSA_is_opaque(const RSA *rsa);
 
-/* RSA_supports_digest returns one if |rsa| supports signing digests
- * of type |md|. Otherwise it returns zero. */
-OPENSSL_EXPORT int RSA_supports_digest(const RSA *rsa, const EVP_MD *md);
-
-/* RSAPublicKey_dup allocates a fresh |RSA| and copies the public key from
- * |rsa| into it. It returns the fresh |RSA| object, or NULL on error. */
+// RSAPublicKey_dup allocates a fresh |RSA| and copies the public key from
+// |rsa| into it. It returns the fresh |RSA| object, or NULL on error.
 OPENSSL_EXPORT RSA *RSAPublicKey_dup(const RSA *rsa);
 
-/* RSAPrivateKey_dup allocates a fresh |RSA| and copies the private key from
- * |rsa| into it. It returns the fresh |RSA| object, or NULL on error. */
+// RSAPrivateKey_dup allocates a fresh |RSA| and copies the private key from
+// |rsa| into it. It returns the fresh |RSA| object, or NULL on error.
 OPENSSL_EXPORT RSA *RSAPrivateKey_dup(const RSA *rsa);
 
-/* RSA_check_key performs basic validatity tests on |rsa|. It returns one if
- * they pass and zero otherwise. Opaque keys and public keys always pass. If it
- * returns zero then a more detailed error is available on the error queue. */
+// RSA_check_key performs basic validity tests on |rsa|. It returns one if
+// they pass and zero otherwise. Opaque keys and public keys always pass. If it
+// returns zero then a more detailed error is available on the error queue.
 OPENSSL_EXPORT int RSA_check_key(const RSA *rsa);
 
-/* RSA_recover_crt_params uses |rsa->n|, |rsa->d| and |rsa->e| in order to
- * calculate the two primes used and thus the precomputed, CRT values. These
- * values are set in the |p|, |q|, |dmp1|, |dmq1| and |iqmp| members of |rsa|,
- * which must be |NULL| on entry. It returns one on success and zero
- * otherwise. */
-OPENSSL_EXPORT int RSA_recover_crt_params(RSA *rsa);
-
-/* RSA_verify_PKCS1_PSS_mgf1 verifies that |EM| is a correct PSS padding of
- * |mHash|, where |mHash| is a digest produced by |Hash|. |EM| must point to
- * exactly |RSA_size(rsa)| bytes of data. The |mgf1Hash| argument specifies the
- * hash function for generating the mask. If NULL, |Hash| is used. The |sLen|
- * argument specifies the expected salt length in bytes. If |sLen| is -1 then
- * the salt length is the same as the hash length. If -2, then the salt length
- * is recovered and all values accepted.
- *
- * If unsure, use -1.
- *
- * It returns one on success or zero on error. */
+// RSA_check_fips performs public key validity tests on |key|. It returns one
+// if they pass and zero otherwise. Opaque keys always fail.
+OPENSSL_EXPORT int RSA_check_fips(RSA *key);
+
+// RSA_verify_PKCS1_PSS_mgf1 verifies that |EM| is a correct PSS padding of
+// |mHash|, where |mHash| is a digest produced by |Hash|. |EM| must point to
+// exactly |RSA_size(rsa)| bytes of data. The |mgf1Hash| argument specifies the
+// hash function for generating the mask. If NULL, |Hash| is used. The |sLen|
+// argument specifies the expected salt length in bytes. If |sLen| is -1 then
+// the salt length is the same as the hash length. If -2, then the salt length
+// is recovered and all values accepted.
+//
+// If unsure, use -1.
+//
+// It returns one on success or zero on error.
+//
+// This function implements only the low-level padding logic. Use
+// |RSA_verify_pss_mgf1| instead.
 OPENSSL_EXPORT int RSA_verify_PKCS1_PSS_mgf1(RSA *rsa, const uint8_t *mHash,
                                              const EVP_MD *Hash,
                                              const EVP_MD *mgf1Hash,
                                              const uint8_t *EM, int sLen);
 
-/* RSA_padding_add_PKCS1_PSS_mgf1 writes a PSS padding of |mHash| to |EM|,
- * where |mHash| is a digest produced by |Hash|. |RSA_size(rsa)| bytes of
- * output will be written to |EM|. The |mgf1Hash| argument specifies the hash
- * function for generating the mask. If NULL, |Hash| is used. The |sLen|
- * argument specifies the expected salt length in bytes. If |sLen| is -1 then
- * the salt length is the same as the hash length. If -2, then the salt length
- * is maximal given the space in |EM|.
- *
- * It returns one on success or zero on error. */
+// RSA_padding_add_PKCS1_PSS_mgf1 writes a PSS padding of |mHash| to |EM|,
+// where |mHash| is a digest produced by |Hash|. |RSA_size(rsa)| bytes of
+// output will be written to |EM|. The |mgf1Hash| argument specifies the hash
+// function for generating the mask. If NULL, |Hash| is used. The |sLen|
+// argument specifies the expected salt length in bytes. If |sLen| is -1 then
+// the salt length is the same as the hash length. If -2, then the salt length
+// is maximal given the space in |EM|.
+//
+// It returns one on success or zero on error.
+//
+// This function implements only the low-level padding logic. Use
+// |RSA_sign_pss_mgf1| instead.
 OPENSSL_EXPORT int RSA_padding_add_PKCS1_PSS_mgf1(RSA *rsa, uint8_t *EM,
                                                   const uint8_t *mHash,
                                                   const EVP_MD *Hash,
                                                   const EVP_MD *mgf1Hash,
                                                   int sLen);
 
-/* RSA_padding_add_PKCS1_OAEP_mgf1 writes an OAEP padding of |from| to |to|
- * with the given parameters and hash functions. If |md| is NULL then SHA-1 is
- * used. If |mgf1md| is NULL then the value of |md| is used (which means SHA-1
- * if that, in turn, is NULL).
- *
- * It returns one on success or zero on error. */
+// RSA_padding_add_PKCS1_OAEP_mgf1 writes an OAEP padding of |from| to |to|
+// with the given parameters and hash functions. If |md| is NULL then SHA-1 is
+// used. If |mgf1md| is NULL then the value of |md| is used (which means SHA-1
+// if that, in turn, is NULL).
+//
+// It returns one on success or zero on error.
 OPENSSL_EXPORT int RSA_padding_add_PKCS1_OAEP_mgf1(
-    uint8_t *to, unsigned to_len, const uint8_t *from, unsigned from_len,
-    const uint8_t *param, unsigned param_len, const EVP_MD *md,
+    uint8_t *to, size_t to_len, const uint8_t *from, size_t from_len,
+    const uint8_t *param, size_t param_len, const EVP_MD *md,
     const EVP_MD *mgf1md);
 
-/* RSA_add_pkcs1_prefix builds a version of |msg| prefixed with the DigestInfo
- * header for the given hash function and sets |out_msg| to point to it. On
- * successful return, |*out_msg| may be allocated memory and, if so,
- * |*is_alloced| will be 1. */
+// RSA_add_pkcs1_prefix builds a version of |msg| prefixed with the DigestInfo
+// header for the given hash function and sets |out_msg| to point to it. On
+// successful return, if |*is_alloced| is one, the caller must release
+// |*out_msg| with |OPENSSL_free|.
 OPENSSL_EXPORT int RSA_add_pkcs1_prefix(uint8_t **out_msg, size_t *out_msg_len,
                                         int *is_alloced, int hash_nid,
                                         const uint8_t *msg, size_t msg_len);
 
 
-/* ASN.1 functions. */
+// ASN.1 functions.
 
-/* RSA_parse_public_key parses a DER-encoded RSAPublicKey structure (RFC 3447)
- * from |cbs| and advances |cbs|. It returns a newly-allocated |RSA| or NULL on
- * error. */
+// RSA_parse_public_key parses a DER-encoded RSAPublicKey structure (RFC 3447)
+// from |cbs| and advances |cbs|. It returns a newly-allocated |RSA| or NULL on
+// error.
 OPENSSL_EXPORT RSA *RSA_parse_public_key(CBS *cbs);
 
-/* RSA_parse_public_key_buggy behaves like |RSA_parse_public_key|, but it
- * tolerates some invalid encodings. Do not use this function. */
+// RSA_parse_public_key_buggy behaves like |RSA_parse_public_key|, but it
+// tolerates some invalid encodings. Do not use this function.
 OPENSSL_EXPORT RSA *RSA_parse_public_key_buggy(CBS *cbs);
 
-/* RSA_public_key_from_bytes parses |in| as a DER-encoded RSAPublicKey structure
- * (RFC 3447). It returns a newly-allocated |RSA| or NULL on error. */
+// RSA_public_key_from_bytes parses |in| as a DER-encoded RSAPublicKey structure
+// (RFC 3447). It returns a newly-allocated |RSA| or NULL on error.
 OPENSSL_EXPORT RSA *RSA_public_key_from_bytes(const uint8_t *in, size_t in_len);
 
-/* RSA_marshal_public_key marshals |rsa| as a DER-encoded RSAPublicKey structure
- * (RFC 3447) and appends the result to |cbb|. It returns one on success and
- * zero on failure. */
+// RSA_marshal_public_key marshals |rsa| as a DER-encoded RSAPublicKey structure
+// (RFC 3447) and appends the result to |cbb|. It returns one on success and
+// zero on failure.
 OPENSSL_EXPORT int RSA_marshal_public_key(CBB *cbb, const RSA *rsa);
 
-/* RSA_public_key_to_bytes marshals |rsa| as a DER-encoded RSAPublicKey
- * structure (RFC 3447) and, on success, sets |*out_bytes| to a newly allocated
- * buffer containing the result and returns one. Otherwise, it returns zero. The
- * result should be freed with |OPENSSL_free|. */
+// RSA_public_key_to_bytes marshals |rsa| as a DER-encoded RSAPublicKey
+// structure (RFC 3447) and, on success, sets |*out_bytes| to a newly allocated
+// buffer containing the result and returns one. Otherwise, it returns zero. The
+// result should be freed with |OPENSSL_free|.
 OPENSSL_EXPORT int RSA_public_key_to_bytes(uint8_t **out_bytes, size_t *out_len,
                                            const RSA *rsa);
 
-/* RSA_parse_private_key parses a DER-encoded RSAPrivateKey structure (RFC 3447)
- * from |cbs| and advances |cbs|. It returns a newly-allocated |RSA| or NULL on
- * error. */
+// RSA_parse_private_key parses a DER-encoded RSAPrivateKey structure (RFC 3447)
+// from |cbs| and advances |cbs|. It returns a newly-allocated |RSA| or NULL on
+// error.
 OPENSSL_EXPORT RSA *RSA_parse_private_key(CBS *cbs);
 
-/* RSA_private_key_from_bytes parses |in| as a DER-encoded RSAPrivateKey
- * structure (RFC 3447). It returns a newly-allocated |RSA| or NULL on error. */
+// RSA_private_key_from_bytes parses |in| as a DER-encoded RSAPrivateKey
+// structure (RFC 3447). It returns a newly-allocated |RSA| or NULL on error.
 OPENSSL_EXPORT RSA *RSA_private_key_from_bytes(const uint8_t *in,
                                                size_t in_len);
 
-/* RSA_marshal_private_key marshals |rsa| as a DER-encoded RSAPrivateKey
- * structure (RFC 3447) and appends the result to |cbb|. It returns one on
- * success and zero on failure. */
+// RSA_marshal_private_key marshals |rsa| as a DER-encoded RSAPrivateKey
+// structure (RFC 3447) and appends the result to |cbb|. It returns one on
+// success and zero on failure.
 OPENSSL_EXPORT int RSA_marshal_private_key(CBB *cbb, const RSA *rsa);
 
-/* RSA_private_key_to_bytes marshals |rsa| as a DER-encoded RSAPrivateKey
- * structure (RFC 3447) and, on success, sets |*out_bytes| to a newly allocated
- * buffer containing the result and returns one. Otherwise, it returns zero. The
- * result should be freed with |OPENSSL_free|. */
+// RSA_private_key_to_bytes marshals |rsa| as a DER-encoded RSAPrivateKey
+// structure (RFC 3447) and, on success, sets |*out_bytes| to a newly allocated
+// buffer containing the result and returns one. Otherwise, it returns zero. The
+// result should be freed with |OPENSSL_free|.
 OPENSSL_EXPORT int RSA_private_key_to_bytes(uint8_t **out_bytes,
                                             size_t *out_len, const RSA *rsa);
 
 
-/* ex_data functions.
- *
- * See |ex_data.h| for details. */
+// ex_data functions.
+//
+// See |ex_data.h| for details.
 
 OPENSSL_EXPORT int RSA_get_ex_new_index(long argl, void *argp,
                                         CRYPTO_EX_unused *unused,
-                                        CRYPTO_EX_dup *dup_func,
+                                        CRYPTO_EX_dup *dup_unused,
                                         CRYPTO_EX_free *free_func);
-OPENSSL_EXPORT int RSA_set_ex_data(RSA *r, int idx, void *arg);
-OPENSSL_EXPORT void *RSA_get_ex_data(const RSA *r, int idx);
+OPENSSL_EXPORT int RSA_set_ex_data(RSA *rsa, int idx, void *arg);
+OPENSSL_EXPORT void *RSA_get_ex_data(const RSA *rsa, int idx);
 
 
-/* Flags. */
+// Flags.
 
-/* RSA_FLAG_OPAQUE specifies that this RSA_METHOD does not expose its key
- * material. This may be set if, for instance, it is wrapping some other crypto
- * API, like a platform key store. */
+// RSA_FLAG_OPAQUE specifies that this RSA_METHOD does not expose its key
+// material. This may be set if, for instance, it is wrapping some other crypto
+// API, like a platform key store.
 #define RSA_FLAG_OPAQUE 1
 
-/* Deprecated and ignored. */
+// Deprecated and ignored.
 #define RSA_FLAG_CACHE_PUBLIC 2
 
-/* Deprecated and ignored. */
+// Deprecated and ignored.
 #define RSA_FLAG_CACHE_PRIVATE 4
 
-/* RSA_FLAG_NO_BLINDING disables blinding of private operations, which is a
- * dangerous thing to do. It is deprecated and should not be used. It will
- * be ignored whenever possible.
- *
- * This flag must be used if a key without the public exponent |e| is used for
- * private key operations; avoid using such keys whenever possible. */
+// RSA_FLAG_NO_BLINDING disables blinding of private operations, which is a
+// dangerous thing to do. It is deprecated and should not be used. It will
+// be ignored whenever possible.
+//
+// This flag must be used if a key without the public exponent |e| is used for
+// private key operations; avoid using such keys whenever possible.
 #define RSA_FLAG_NO_BLINDING 8
 
-/* RSA_FLAG_EXT_PKEY is deprecated and ignored. */
+// RSA_FLAG_EXT_PKEY is deprecated and ignored.
 #define RSA_FLAG_EXT_PKEY 0x20
 
-/* RSA_FLAG_SIGN_VER causes the |sign| and |verify| functions of |rsa_meth_st|
- * to be called when set. */
+// RSA_FLAG_SIGN_VER causes the |sign| and |verify| functions of |rsa_meth_st|
+// to be called when set.
 #define RSA_FLAG_SIGN_VER 0x40
 
 
-/* RSA public exponent values. */
+// RSA public exponent values.
 
 #define RSA_3 0x3
 #define RSA_F4 0x10001
 
 
-/* Deprecated functions. */
+// Deprecated functions.
 
-/* RSA_blinding_on returns one. */
+// RSA_blinding_on returns one.
 OPENSSL_EXPORT int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
 
-/* RSA_generate_key behaves like |RSA_generate_key_ex|, which is what you
- * should use instead. It returns NULL on error, or a newly-allocated |RSA| on
- * success. This function is provided for compatibility only. The |callback|
- * and |cb_arg| parameters must be NULL. */
+// RSA_generate_key behaves like |RSA_generate_key_ex|, which is what you
+// should use instead. It returns NULL on error, or a newly-allocated |RSA| on
+// success. This function is provided for compatibility only. The |callback|
+// and |cb_arg| parameters must be NULL.
 OPENSSL_EXPORT RSA *RSA_generate_key(int bits, unsigned long e, void *callback,
                                      void *cb_arg);
 
-/* d2i_RSAPublicKey parses an ASN.1, DER-encoded, RSA public key from |len|
- * bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
- * is in |*out|. Note that, even if |*out| is already non-NULL on entry, it
- * will not be written to. Rather, a fresh |RSA| is allocated and the previous
- * one is freed. On successful exit, |*inp| is advanced past the DER structure.
- * It returns the result or NULL on error. */
+// d2i_RSAPublicKey parses an ASN.1, DER-encoded, RSA public key from |len|
+// bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
+// is in |*out|. Note that, even if |*out| is already non-NULL on entry, it
+// will not be written to. Rather, a fresh |RSA| is allocated and the previous
+// one is freed. On successful exit, |*inp| is advanced past the DER structure.
+// It returns the result or NULL on error.
 OPENSSL_EXPORT RSA *d2i_RSAPublicKey(RSA **out, const uint8_t **inp, long len);
 
-/* i2d_RSAPublicKey marshals |in| to an ASN.1, DER structure. 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. */
+// i2d_RSAPublicKey marshals |in| to an ASN.1, DER structure. 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.
 OPENSSL_EXPORT int i2d_RSAPublicKey(const RSA *in, uint8_t **outp);
 
-/* d2i_RSAPrivateKey parses an ASN.1, DER-encoded, RSA private key from |len|
- * bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
- * is in |*out|. Note that, even if |*out| is already non-NULL on entry, it
- * will not be written to. Rather, a fresh |RSA| is allocated and the previous
- * one is freed. On successful exit, |*inp| is advanced past the DER structure.
- * It returns the result or NULL on error. */
+// d2i_RSAPrivateKey parses an ASN.1, DER-encoded, RSA private key from |len|
+// bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
+// is in |*out|. Note that, even if |*out| is already non-NULL on entry, it
+// will not be written to. Rather, a fresh |RSA| is allocated and the previous
+// one is freed. On successful exit, |*inp| is advanced past the DER structure.
+// It returns the result or NULL on error.
 OPENSSL_EXPORT RSA *d2i_RSAPrivateKey(RSA **out, const uint8_t **inp, long len);
 
-/* i2d_RSAPrivateKey marshals |in| to an ASN.1, DER structure. 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. */
+// i2d_RSAPrivateKey marshals |in| to an ASN.1, DER structure. 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.
 OPENSSL_EXPORT int i2d_RSAPrivateKey(const RSA *in, uint8_t **outp);
 
-/* RSA_padding_add_PKCS1_PSS acts like |RSA_padding_add_PKCS1_PSS_mgf1| but the
- * |mgf1Hash| parameter of the latter is implicitly set to |Hash|. */
+// RSA_padding_add_PKCS1_PSS acts like |RSA_padding_add_PKCS1_PSS_mgf1| but the
+// |mgf1Hash| parameter of the latter is implicitly set to |Hash|.
+//
+// This function implements only the low-level padding logic. Use
+// |RSA_sign_pss_mgf1| instead.
 OPENSSL_EXPORT int RSA_padding_add_PKCS1_PSS(RSA *rsa, uint8_t *EM,
                                              const uint8_t *mHash,
                                              const EVP_MD *Hash, int sLen);
 
-/* RSA_verify_PKCS1_PSS acts like |RSA_verify_PKCS1_PSS_mgf1| but the
- * |mgf1Hash| parameter of the latter is implicitly set to |Hash|. */
+// RSA_verify_PKCS1_PSS acts like |RSA_verify_PKCS1_PSS_mgf1| but the
+// |mgf1Hash| parameter of the latter is implicitly set to |Hash|.
+//
+// This function implements only the low-level padding logic. Use
+// |RSA_verify_pss_mgf1| instead.
 OPENSSL_EXPORT int RSA_verify_PKCS1_PSS(RSA *rsa, const uint8_t *mHash,
                                         const EVP_MD *Hash, const uint8_t *EM,
                                         int sLen);
 
-/* RSA_padding_add_PKCS1_OAEP acts like |RSA_padding_add_PKCS1_OAEP_mgf1| but
- * the |md| and |mgf1md| parameters of the latter are implicitly set to NULL,
- * which means SHA-1. */
-OPENSSL_EXPORT int RSA_padding_add_PKCS1_OAEP(uint8_t *to, unsigned to_len,
+// RSA_padding_add_PKCS1_OAEP acts like |RSA_padding_add_PKCS1_OAEP_mgf1| but
+// the |md| and |mgf1md| parameters of the latter are implicitly set to NULL,
+// which means SHA-1.
+OPENSSL_EXPORT int RSA_padding_add_PKCS1_OAEP(uint8_t *to, size_t to_len,
                                               const uint8_t *from,
-                                              unsigned from_len,
+                                              size_t from_len,
                                               const uint8_t *param,
-                                              unsigned param_len);
+                                              size_t param_len);
 
 
 struct rsa_meth_st {
@@ -534,66 +594,38 @@ struct rsa_meth_st {
   int (*init)(RSA *rsa);
   int (*finish)(RSA *rsa);
 
-  /* size returns the size of the RSA modulus in bytes. */
+  // size returns the size of the RSA modulus in bytes.
   size_t (*size)(const RSA *rsa);
 
   int (*sign)(int type, const uint8_t *m, unsigned int m_length,
               uint8_t *sigret, unsigned int *siglen, const RSA *rsa);
 
-  /* Ignored. Set this to NULL. */
-  int (*verify)(int dtype, const uint8_t *m, unsigned int m_length,
-                const uint8_t *sigbuf, unsigned int siglen, const RSA *rsa);
-
-
-  /* These functions mirror the |RSA_*| functions of the same name. */
-  int (*encrypt)(RSA *rsa, size_t *out_len, uint8_t *out, size_t max_out,
-                 const uint8_t *in, size_t in_len, int padding);
+  // These functions mirror the |RSA_*| functions of the same name.
   int (*sign_raw)(RSA *rsa, size_t *out_len, uint8_t *out, size_t max_out,
                   const uint8_t *in, size_t in_len, int padding);
-
   int (*decrypt)(RSA *rsa, size_t *out_len, uint8_t *out, size_t max_out,
                  const uint8_t *in, size_t in_len, int padding);
-  /* Ignored. Set this to NULL. */
-  int (*verify_raw)(RSA *rsa, size_t *out_len, uint8_t *out, size_t max_out,
-                    const uint8_t *in, size_t in_len, int padding);
-
-  /* private_transform takes a big-endian integer from |in|, calculates the
-   * d'th power of it, modulo the RSA modulus and writes the result as a
-   * big-endian integer to |out|. Both |in| and |out| are |len| bytes long and
-   * |len| is always equal to |RSA_size(rsa)|. If the result of the transform
-   * can be represented in fewer than |len| bytes, then |out| must be zero
-   * padded on the left.
-   *
-   * It returns one on success and zero otherwise.
-   *
-   * RSA decrypt and sign operations will call this, thus an ENGINE might wish
-   * to override it in order to avoid having to implement the padding
-   * functionality demanded by those, higher level, operations. */
+
+  // private_transform takes a big-endian integer from |in|, calculates the
+  // d'th power of it, modulo the RSA modulus and writes the result as a
+  // big-endian integer to |out|. Both |in| and |out| are |len| bytes long and
+  // |len| is always equal to |RSA_size(rsa)|. If the result of the transform
+  // can be represented in fewer than |len| bytes, then |out| must be zero
+  // padded on the left.
+  //
+  // It returns one on success and zero otherwise.
+  //
+  // RSA decrypt and sign operations will call this, thus an ENGINE might wish
+  // to override it in order to avoid having to implement the padding
+  // functionality demanded by those, higher level, operations.
   int (*private_transform)(RSA *rsa, uint8_t *out, const uint8_t *in,
                            size_t len);
 
-  /* mod_exp is deprecated and ignored. Set it to NULL. */
-  int (*mod_exp)(BIGNUM *r0, const BIGNUM *I, RSA *rsa, BN_CTX *ctx);
-
-  /* bn_mod_exp is deprecated and ignored. Set it to NULL. */
-  int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
-                    const BIGNUM *m, BN_CTX *ctx,
-                    const BN_MONT_CTX *mont);
-
   int flags;
-
-  int (*keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
-
-  int (*multi_prime_keygen)(RSA *rsa, int bits, int num_primes, BIGNUM *e,
-                            BN_GENCB *cb);
-
-  /* supports_digest returns one if |rsa| supports digests of type
-   * |md|. If null, it is assumed that all digests are supported. */
-  int (*supports_digest)(const RSA *rsa, const EVP_MD *md);
 };
 
 
-/* Private functions. */
+// Private functions.
 
 typedef struct bn_blinding_st BN_BLINDING;
 
@@ -609,35 +641,33 @@ struct rsa_st {
   BIGNUM *dmq1;
   BIGNUM *iqmp;
 
-  STACK_OF(RSA_additional_prime) *additional_primes;
-
-  /* be careful using this if the RSA structure is shared */
+  // be careful using this if the RSA structure is shared
   CRYPTO_EX_DATA ex_data;
   CRYPTO_refcount_t references;
   int flags;
 
   CRYPTO_MUTEX lock;
 
-  /* Used to cache montgomery values. The creation of these values is protected
-   * by |lock|. */
+  // Used to cache montgomery values. The creation of these values is protected
+  // by |lock|.
   BN_MONT_CTX *mont_n;
   BN_MONT_CTX *mont_p;
   BN_MONT_CTX *mont_q;
 
-  /* num_blindings contains the size of the |blindings| and |blindings_inuse|
-   * arrays. This member and the |blindings_inuse| array are protected by
-   * |lock|. */
+  // num_blindings contains the size of the |blindings| and |blindings_inuse|
+  // arrays. This member and the |blindings_inuse| array are protected by
+  // |lock|.
   unsigned num_blindings;
-  /* blindings is an array of BN_BLINDING structures that can be reserved by a
-   * thread by locking |lock| and changing the corresponding element in
-   * |blindings_inuse| from 0 to 1. */
+  // blindings is an array of BN_BLINDING structures that can be reserved by a
+  // thread by locking |lock| and changing the corresponding element in
+  // |blindings_inuse| from 0 to 1.
   BN_BLINDING **blindings;
   unsigned char *blindings_inuse;
 };
 
 
 #if defined(__cplusplus)
-}  /* extern C */
+}  // extern C
 
 extern "C++" {
 
@@ -647,7 +677,7 @@ BORINGSSL_MAKE_DELETER(RSA, RSA_free)
 
 }  // namespace bssl
 
-}  /* extern C++ */
+}  // extern C++
 
 #endif
 
@@ -697,5 +727,6 @@ BORINGSSL_MAKE_DELETER(RSA, RSA_free)
 #define RSA_R_UNKNOWN_PADDING_TYPE 143
 #define RSA_R_VALUE_MISSING 144
 #define RSA_R_WRONG_SIGNATURE_LENGTH 145
+#define RSA_R_PUBLIC_KEY_VALIDATION_FAILED 146
 
-#endif  /* OPENSSL_HEADER_RSA_H */
+#endif  // OPENSSL_HEADER_RSA_H