grpc 1.84.1 → 1.85.0.pre1

data/third_party/boringssl-with-bazel/include/openssl/trust_token.h

@@ -30,12 +30,13 @@ extern "C" {
 // limited private metadata.
 //
 // References:
-// https://eprint.iacr.org/2020/072.pdf
-// https://github.com/ietf-wg-privacypass/base-drafts
-// https://github.com/WICG/trust-token-api/blob/main/README.md
+// * https://eprint.iacr.org/2020/072.pdf
+// * https://github.com/ietf-wg-privacypass/base-drafts
+// * https://github.com/WICG/trust-token-api/blob/main/README.md
 //
 // WARNING: This API is unstable and subject to change.
 
+
 // TRUST_TOKEN_experiment_v1 is an experimental Trust Tokens protocol using
 // PMBTokens and P-384.
 OPENSSL_EXPORT const TRUST_TOKEN_METHOD *TRUST_TOKEN_experiment_v1(void);
@@ -66,25 +67,25 @@ struct trust_token_st {
 
 DEFINE_STACK_OF(TRUST_TOKEN)
 
-// TRUST_TOKEN_new creates a newly-allocated |TRUST_TOKEN| with value |data| or
+// TRUST_TOKEN_new creates a newly-allocated `TRUST_TOKEN` with value `data` or
 // NULL on allocation failure.
 OPENSSL_EXPORT TRUST_TOKEN *TRUST_TOKEN_new(const uint8_t *data, size_t len);
 
-// TRUST_TOKEN_free releases memory associated with |token|.
+// TRUST_TOKEN_free releases memory associated with `token`.
 OPENSSL_EXPORT void TRUST_TOKEN_free(TRUST_TOKEN *token);
 
 #define TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE 512
 #define TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE 512
 
-// TRUST_TOKEN_generate_key creates a new Trust Token keypair labeled with |id|
+// TRUST_TOKEN_generate_key creates a new Trust Token keypair labeled with `id`
 // and serializes the private and public keys, writing the private key to
-// |out_priv_key| and setting |*out_priv_key_len| to the number of bytes
-// written, and writing the public key to |out_pub_key| and setting
-// |*out_pub_key_len| to the number of bytes written.
+// `out_priv_key` and setting `*out_priv_key_len` to the number of bytes
+// written, and writing the public key to `out_pub_key` and setting
+// `*out_pub_key_len` to the number of bytes written.
 //
-// At most |max_priv_key_len| and |max_pub_key_len| bytes are written. In order
+// At most `max_priv_key_len` and `max_pub_key_len` bytes are written. In order
 // to ensure success, these should be at least
-// |TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE| and |TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE|.
+// `TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE` and `TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE`.
 //
 // This function returns one on success or zero on error.
 OPENSSL_EXPORT int TRUST_TOKEN_generate_key(
@@ -93,15 +94,15 @@ OPENSSL_EXPORT int TRUST_TOKEN_generate_key(
     size_t *out_pub_key_len, size_t max_pub_key_len, uint32_t id);
 
 // TRUST_TOKEN_derive_key_from_secret deterministically derives a new Trust
-// Token keypair labeled with |id| from an input |secret| and serializes the
-// private and public keys, writing the private key to |out_priv_key| and
-// setting |*out_priv_key_len| to the number of bytes written, and writing the
-// public key to |out_pub_key| and setting |*out_pub_key_len| to the number of
+// Token keypair labeled with `id` from an input `secret` and serializes the
+// private and public keys, writing the private key to `out_priv_key` and
+// setting `*out_priv_key_len` to the number of bytes written, and writing the
+// public key to `out_pub_key` and setting `*out_pub_key_len` to the number of
 // bytes written.
 //
-// At most |max_priv_key_len| and |max_pub_key_len| bytes are written. In order
+// At most `max_priv_key_len` and `max_pub_key_len` bytes are written. In order
 // to ensure success, these should be at least
-// |TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE| and |TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE|.
+// `TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE` and `TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE`.
 //
 // This function returns one on success or zero on error.
 OPENSSL_EXPORT int TRUST_TOKEN_derive_key_from_secret(
@@ -114,22 +115,34 @@ OPENSSL_EXPORT int TRUST_TOKEN_derive_key_from_secret(
 // Trust Token client implementation.
 //
 // These functions implements the client half of the Trust Token protocol. A
-// single |TRUST_TOKEN_CLIENT| can perform a single protocol operation.
+// single `TRUST_TOKEN_CLIENT` can perform a single protocol operation.
 
-// TRUST_TOKEN_CLIENT_new returns a newly-allocated |TRUST_TOKEN_CLIENT|
-// configured to use a max batchsize of |max_batchsize| or NULL on error.
-// Issuance requests must be made in batches smaller than |max_batchsize|. This
-// function will return an error if |max_batchsize| is too large for Trust
+// TRUST_TOKEN_CLIENT_new returns a newly-allocated `TRUST_TOKEN_CLIENT`
+// configured to use a max batchsize of `max_batchsize` or NULL on error.
+// Issuance requests must be made in batches smaller than `max_batchsize`. This
+// function will return an error if `max_batchsize` is too large for Trust
 // Tokens.
 OPENSSL_EXPORT TRUST_TOKEN_CLIENT *TRUST_TOKEN_CLIENT_new(
     const TRUST_TOKEN_METHOD *method, size_t max_batchsize);
 
-// TRUST_TOKEN_CLIENT_free releases memory associated with |ctx|.
+// TRUST_TOKEN_CLIENT_free releases memory associated with `ctx`.
 OPENSSL_EXPORT void TRUST_TOKEN_CLIENT_free(TRUST_TOKEN_CLIENT *ctx);
 
-// TRUST_TOKEN_CLIENT_add_key configures the |ctx| to support the public key
-// |key|. It sets |*out_key_index| to the index this key has been configured to.
-// It returns one on success or zero on error if the |key| can't be parsed or
+// TRUST_TOKEN_CLIENT_dup_for_testing returns a newly-allocated copy of `ctx`,
+// or NULL on error. This may be useful for testing the library, e.g. to
+// benchmark an individual operation.
+//
+// WARNING: This function should never be used in production. A
+// `TRUST_TOKEN_CLIENT` maintains single-use state between
+// `TRUST_TOKEN_CLIENT_begin_issuance` and `TRUST_TOKEN_CLIENT_finish_issuance`
+// operations. Cloning this state will cause tokens to be linkable and no longer
+// anonymized.
+OPENSSL_EXPORT TRUST_TOKEN_CLIENT *TRUST_TOKEN_CLIENT_dup_for_testing(
+    const TRUST_TOKEN_CLIENT *ctx);
+
+// TRUST_TOKEN_CLIENT_add_key configures the `ctx` to support the public key
+// `key`. It sets `*out_key_index` to the index this key has been configured to.
+// It returns one on success or zero on error if the `key` can't be parsed or
 // too many keys have been configured.
 OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_add_key(TRUST_TOKEN_CLIENT *ctx,
                                               size_t *out_key_index,
@@ -141,10 +154,10 @@ OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_add_key(TRUST_TOKEN_CLIENT *ctx,
 OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_set_srr_key(TRUST_TOKEN_CLIENT *ctx,
                                                   EVP_PKEY *key);
 
-// TRUST_TOKEN_CLIENT_begin_issuance produces a request for |count| trust tokens
-// and serializes the request into a newly-allocated buffer, setting |*out| to
-// that buffer and |*out_len| to its length. The caller takes ownership of the
-// buffer and must call |OPENSSL_free| when done. It returns one on success and
+// TRUST_TOKEN_CLIENT_begin_issuance produces a request for `count` trust tokens
+// and serializes the request into a newly-allocated buffer, setting `*out` to
+// that buffer and `*out_len` to its length. The caller takes ownership of the
+// buffer and must call `OPENSSL_free` when done. It returns one on success and
 // zero on error.
 OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_issuance(TRUST_TOKEN_CLIENT *ctx,
                                                      uint8_t **out,
@@ -152,20 +165,20 @@ OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_issuance(TRUST_TOKEN_CLIENT *ctx,
                                                      size_t count);
 
 // TRUST_TOKEN_CLIENT_begin_issuance_over_message produces a request for a trust
-// token derived from |msg| and serializes the request into a newly-allocated
-// buffer, setting |*out| to that buffer and |*out_len| to its length. The
-// caller takes ownership of the buffer and must call |OPENSSL_free| when done.
+// token derived from `msg` and serializes the request into a newly-allocated
+// buffer, setting `*out` to that buffer and `*out_len` to its length. The
+// caller takes ownership of the buffer and must call `OPENSSL_free` when done.
 // It returns one on success and zero on error.
 OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_issuance_over_message(
     TRUST_TOKEN_CLIENT *ctx, uint8_t **out, size_t *out_len, size_t count,
     const uint8_t *msg, size_t msg_len);
 
-// TRUST_TOKEN_CLIENT_finish_issuance consumes |response| from the issuer and
+// TRUST_TOKEN_CLIENT_finish_issuance consumes `response` from the issuer and
 // extracts the tokens, returning a list of tokens and the index of the key used
-// to sign the tokens in |*out_key_index|. The caller can use this to determine
+// to sign the tokens in `*out_key_index`. The caller can use this to determine
 // what key was used in an issuance and to drop tokens if a new key commitment
 // arrives without the specified key present. The caller takes ownership of the
-// list and must call |sk_TRUST_TOKEN_pop_free| when done. The list is empty if
+// list and must call `sk_TRUST_TOKEN_pop_free` when done. The list is empty if
 // issuance fails.
 OPENSSL_EXPORT STACK_OF(TRUST_TOKEN) *
     TRUST_TOKEN_CLIENT_finish_issuance(TRUST_TOKEN_CLIENT *ctx,
@@ -175,23 +188,23 @@ OPENSSL_EXPORT STACK_OF(TRUST_TOKEN) *
 
 
 // TRUST_TOKEN_CLIENT_begin_redemption produces a request to redeem a token
-// |token| and receive a signature over |data| and serializes the request into
-// a newly-allocated buffer, setting |*out| to that buffer and |*out_len| to
-// its length. |time| is the number of seconds since the UNIX epoch and used to
+// `token` and receive a signature over `data` and serializes the request into
+// a newly-allocated buffer, setting `*out` to that buffer and `*out_len` to
+// its length. `time` is the number of seconds since the UNIX epoch and used to
 // verify the validity of the issuer's response in TrustTokenV1 and ignored in
 // other versions. The caller takes ownership of the buffer and must call
-// |OPENSSL_free| when done. It returns one on success or zero on error.
+// `OPENSSL_free` when done. It returns one on success or zero on error.
 OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_redemption(
     TRUST_TOKEN_CLIENT *ctx, uint8_t **out, size_t *out_len,
     const TRUST_TOKEN *token, const uint8_t *data, size_t data_len,
     uint64_t time);
 
-// TRUST_TOKEN_CLIENT_finish_redemption consumes |response| from the issuer. In
-// |TRUST_TOKEN_experiment_v1|, it then verifies the SRR and if valid  sets
-// |*out_rr| and |*out_rr_len| (respectively, |*out_sig| and |*out_sig_len|)
+// TRUST_TOKEN_CLIENT_finish_redemption consumes `response` from the issuer. In
+// `TRUST_TOKEN_experiment_v1`, it then verifies the SRR and if valid  sets
+// `*out_rr` and `*out_rr_len` (respectively, `*out_sig` and `*out_sig_len`)
 // to a newly-allocated buffer containing the SRR (respectively, the SRR
-// signature). In other versions, it sets |*out_rr| and |*out_rr_len|
-// to a newly-allocated buffer containing |response| and leaves all validation
+// signature). In other versions, it sets `*out_rr` and `*out_rr_len`
+// to a newly-allocated buffer containing `response` and leaves all validation
 // to the caller. It returns one on success or zero on failure.
 OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_finish_redemption(
     TRUST_TOKEN_CLIENT *ctx, uint8_t **out_rr, size_t *out_rr_len,
@@ -202,26 +215,26 @@ OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_finish_redemption(
 // Trust Token issuer implementation.
 //
 // These functions implement the issuer half of the Trust Token protocol. A
-// |TRUST_TOKEN_ISSUER| can be reused across multiple protocol operations. It
+// `TRUST_TOKEN_ISSUER` can be reused across multiple protocol operations. It
 // may be used concurrently on multiple threads by non-mutating functions,
 // provided no other thread is concurrently calling a mutating function.
-// Functions which take a |const| pointer are non-mutating and functions which
-// take a non-|const| pointer are mutating.
+// Functions which take a `const` pointer are non-mutating and functions which
+// take a non-`const` pointer are mutating.
 
-// TRUST_TOKEN_ISSUER_new returns a newly-allocated |TRUST_TOKEN_ISSUER|
-// configured to use a max batchsize of |max_batchsize| or NULL on error.
-// Issuance requests must be made in batches smaller than |max_batchsize|. This
-// function will return an error if |max_batchsize| is too large for Trust
+// TRUST_TOKEN_ISSUER_new returns a newly-allocated `TRUST_TOKEN_ISSUER`
+// configured to use a max batchsize of `max_batchsize` or NULL on error.
+// Issuance requests must be made in batches smaller than `max_batchsize`. This
+// function will return an error if `max_batchsize` is too large for Trust
 // Tokens.
 OPENSSL_EXPORT TRUST_TOKEN_ISSUER *TRUST_TOKEN_ISSUER_new(
     const TRUST_TOKEN_METHOD *method, size_t max_batchsize);
 
-// TRUST_TOKEN_ISSUER_free releases memory associated with |ctx|.
+// TRUST_TOKEN_ISSUER_free releases memory associated with `ctx`.
 OPENSSL_EXPORT void TRUST_TOKEN_ISSUER_free(TRUST_TOKEN_ISSUER *ctx);
 
-// TRUST_TOKEN_ISSUER_add_key configures the |ctx| to support the private key
-// |key|. It must be a private key returned by |TRUST_TOKEN_generate_key|. It
-// returns one on success or zero on error. This function may fail if the |key|
+// TRUST_TOKEN_ISSUER_add_key configures the `ctx` to support the private key
+// `key`. It must be a private key returned by `TRUST_TOKEN_generate_key`. It
+// returns one on success or zero on error. This function may fail if the `key`
 // can't be parsed or too many keys have been configured.
 OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_add_key(TRUST_TOKEN_ISSUER *ctx,
                                               const uint8_t *key,
@@ -232,39 +245,31 @@ OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_add_key(TRUST_TOKEN_ISSUER *ctx,
 OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_set_srr_key(TRUST_TOKEN_ISSUER *ctx,
                                                   EVP_PKEY *key);
 
-// TRUST_TOKEN_ISSUER_set_metadata_key sets the key used to encrypt the private
-// metadata. The key is a randomly generated bytestring of at least 32 bytes
-// used to encode the private metadata bit in the SRR. It returns one on success
-// and zero on error.
-OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_set_metadata_key(TRUST_TOKEN_ISSUER *ctx,
-                                                       const uint8_t *key,
-                                                       size_t len);
-
-// TRUST_TOKEN_ISSUER_issue ingests |request| for token issuance
-// and generates up to |max_issuance| valid tokens, producing a list of blinded
+// TRUST_TOKEN_ISSUER_issue ingests `request` for token issuance
+// and generates up to `max_issuance` valid tokens, producing a list of blinded
 // tokens and storing the response into a newly-allocated buffer and setting
-// |*out| to that buffer, |*out_len| to its length, and |*out_tokens_issued| to
+// `*out` to that buffer, `*out_len` to its length, and `*out_tokens_issued` to
 // the number of tokens issued. The tokens are issued with public metadata of
-// |public_metadata| and a private metadata value of |private_metadata|.
-// |public_metadata| must be one of the previously configured key IDs.
-// |private_metadata| must be 0 or 1. The caller takes ownership of the buffer
-// and must call |OPENSSL_free| when done. It returns one on success or zero on
+// `public_metadata` and a private metadata value of `private_metadata`.
+// `public_metadata` must be one of the previously configured key IDs.
+// `private_metadata` must be 0 or 1. The caller takes ownership of the buffer
+// and must call `OPENSSL_free` when done. It returns one on success or zero on
 // error.
 OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_issue(
     const TRUST_TOKEN_ISSUER *ctx, uint8_t **out, size_t *out_len,
     size_t *out_tokens_issued, const uint8_t *request, size_t request_len,
     uint32_t public_metadata, uint8_t private_metadata, size_t max_issuance);
 
-// TRUST_TOKEN_ISSUER_redeem ingests a |request| for token redemption and
-// verifies the token. The public metadata is stored in |*out_public|. The
-// private metadata (if any) is stored in |*out_private|. The extracted
-// |TRUST_TOKEN| is stored into a newly-allocated buffer and stored in
-// |*out_token|. The extracted client data is stored into a newly-allocated
-// buffer and stored in |*out_client_data|. The caller takes ownership of each
-// output buffer and must call |OPENSSL_free| when done. It returns one on
+// TRUST_TOKEN_ISSUER_redeem ingests a `request` for token redemption and
+// verifies the token. The public metadata is stored in `*out_public`. The
+// private metadata (if any) is stored in `*out_private`. The extracted
+// `TRUST_TOKEN` is stored into a newly-allocated buffer and stored in
+// `*out_token`. The extracted client data is stored into a newly-allocated
+// buffer and stored in `*out_client_data`. The caller takes ownership of each
+// output buffer and must call `OPENSSL_free` when done. It returns one on
 // success or zero on error.
 //
-// The caller must keep track of all values of |*out_token| seen globally before
+// The caller must keep track of all values of `*out_token` seen globally before
 // returning a response to the client. If the value has been reused, the caller
 // must report an error to the client. Returning a response with replayed values
 // allows an attacker to double-spend tokens.
@@ -274,20 +279,20 @@ OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_redeem(
     size_t *out_client_data_len, const uint8_t *request, size_t request_len);
 
 // TRUST_TOKEN_ISSUER_redeem_raw is a legacy alias for
-// |TRUST_TOKEN_ISSUER_redeem|.
+// `TRUST_TOKEN_ISSUER_redeem`.
 #define TRUST_TOKEN_ISSUER_redeem_raw TRUST_TOKEN_ISSUER_redeem
 
-// TRUST_TOKEN_ISSUER_redeem_over_message ingests a |request| for token
+// TRUST_TOKEN_ISSUER_redeem_over_message ingests a `request` for token
 // redemption and a message and verifies the token and that it is derived from
-// the provided |msg|. The public metadata is stored in
-// |*out_public|. The private metadata (if any) is stored in |*out_private|. The
-// extracted |TRUST_TOKEN| is stored into a newly-allocated buffer and stored in
-// |*out_token|. The extracted client data is stored into a newly-allocated
-// buffer and stored in |*out_client_data|. The caller takes ownership of each
-// output buffer and must call |OPENSSL_free| when done. It returns one on
+// the provided `msg`. The public metadata is stored in
+// `*out_public`. The private metadata (if any) is stored in `*out_private`. The
+// extracted `TRUST_TOKEN` is stored into a newly-allocated buffer and stored in
+// `*out_token`. The extracted client data is stored into a newly-allocated
+// buffer and stored in `*out_client_data`. The caller takes ownership of each
+// output buffer and must call `OPENSSL_free` when done. It returns one on
 // success or zero on error.
 //
-// The caller must keep track of all values of |*out_token| seen globally before
+// The caller must keep track of all values of `*out_token` seen globally before
 // returning a response to the client. If the value has been reused, the caller
 // must report an error to the client. Returning a response with replayed values
 // allows an attacker to double-spend tokens.
@@ -297,10 +302,10 @@ OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_redeem_over_message(
     size_t *out_client_data_len, const uint8_t *request, size_t request_len,
     const uint8_t *msg, size_t msg_len);
 
-// TRUST_TOKEN_decode_private_metadata decodes |encrypted_bit| using the
-// private metadata key specified by a |key| buffer of length |key_len| and the
-// nonce by a |nonce| buffer of length |nonce_len|. The nonce in
-// |TRUST_TOKEN_experiment_v1| is the token-hash field of the SRR. |*out_value|
+// TRUST_TOKEN_decode_private_metadata decodes `encrypted_bit` using the
+// private metadata key specified by a `key` buffer of length `key_len` and the
+// nonce by a `nonce` buffer of length `nonce_len`. The nonce in
+// `TRUST_TOKEN_experiment_v1` is the token-hash field of the SRR. `*out_value`
 // is set to the decrypted value, either zero or one. It returns one on success
 // and zero on error.
 OPENSSL_EXPORT int TRUST_TOKEN_decode_private_metadata(

data/third_party/boringssl-with-bazel/include/openssl/type_check.h

@@ -22,7 +22,7 @@ extern "C" {
 #endif
 
 
-// CHECKED_CAST casts |p| from type |from| to type |to|.
+// CHECKED_CAST casts `p` from type `from` to type `to`.
 //
 // TODO(davidben): Although this macro is not public API and is unused in
 // BoringSSL, wpa_supplicant uses it to define its own stacks. Remove this once