grpc 1.32.0 → 1.35.0

data/include/grpc/compression.h

@@ -41,7 +41,7 @@ GRPCAPI int grpc_compression_algorithm_is_stream(
 /** Parses the \a slice as a grpc_compression_algorithm instance and updating \a
  * algorithm. Returns 1 upon success, 0 otherwise. */
 GRPCAPI int grpc_compression_algorithm_parse(
-    grpc_slice value, grpc_compression_algorithm* algorithm);
+    grpc_slice name, grpc_compression_algorithm* algorithm);
 
 /** Updates \a name with the encoding name corresponding to a valid \a
  * algorithm. Note that \a name is statically allocated and must *not* be freed.

data/include/grpc/grpc.h

@@ -86,8 +86,7 @@ GRPCAPI void grpc_shutdown(void);
     https://github.com/grpc/grpc/issues/15334 */
 GRPCAPI int grpc_is_initialized(void);
 
-/** EXPERIMENTAL. Blocking shut down grpc library.
-    This is only for wrapped language to use now. */
+/** DEPRECATED. Recommend to use grpc_shutdown only */
 GRPCAPI void grpc_shutdown_blocking(void);
 
 /** Return a string representing the current version of grpc */
@@ -219,11 +218,6 @@ GRPCAPI grpc_call* grpc_channel_create_call(
     grpc_completion_queue* completion_queue, grpc_slice method,
     const grpc_slice* host, gpr_timespec deadline, void* reserved);
 
-/** Ping the channels peer (load balanced channels will select one sub-channel
-    to ping); if the channel is not connected, posts a failed. */
-GRPCAPI void grpc_channel_ping(grpc_channel* channel, grpc_completion_queue* cq,
-                               void* tag, void* reserved);
-
 /** Pre-register a method/host pair on a channel.
     method and host are not owned and must remain alive while the channel is
     alive. */
@@ -417,6 +411,20 @@ GRPCAPI void grpc_server_register_completion_queue(grpc_server* server,
                                                    grpc_completion_queue* cq,
                                                    void* reserved);
 
+typedef struct grpc_server_config_fetcher grpc_server_config_fetcher;
+
+/** EXPERIMENTAL.  Creates an xDS config fetcher. */
+GRPCAPI grpc_server_config_fetcher* grpc_server_config_fetcher_xds_create();
+
+/** EXPERIMENTAL.  Destroys a config fetcher. */
+GRPCAPI void grpc_server_config_fetcher_destroy(
+    grpc_server_config_fetcher* config_fetcher);
+
+/** EXPERIMENTAL.  Sets the server's config fetcher.  Takes ownership.
+    Must be called before adding ports */
+GRPCAPI void grpc_server_set_config_fetcher(
+    grpc_server* server, grpc_server_config_fetcher* config_fetcher);
+
 /** Add a HTTP2 over plaintext over tcp listener.
     Returns bound port number on success, 0 on failure.
     REQUIRES: server not started */

data/include/grpc/grpc_security.h

@@ -330,6 +330,14 @@ grpc_service_account_jwt_access_credentials_create(const char* json_key,
                                                    gpr_timespec token_lifetime,
                                                    void* reserved);
 
+/** Builds External Account credentials.
+ - json_string is the JSON string containing the credentials options.
+ - scopes_string contains the scopes to be binded with the credentials.
+   This API is used for experimental purposes for now and may change in the
+ future. */
+GRPCAPI grpc_call_credentials* grpc_external_account_credentials_create(
+    const char* json_string, const char* scopes_string);
+
 /** Creates an Oauth2 Refresh Token credentials object for connecting to Google.
    May return NULL if the input is invalid.
    WARNING: Do NOT use this credentials to connect to a non-google service as
@@ -743,183 +751,181 @@ GRPCAPI grpc_server_credentials* grpc_local_server_credentials_create(
  *  experimental purpose for now and subject to change. */
 typedef struct grpc_tls_error_details grpc_tls_error_details;
 
-/** Config for TLS key materials. It is used for
- *  experimental purpose for now and subject to change. */
-typedef struct grpc_tls_key_materials_config grpc_tls_key_materials_config;
-
-/** Config for TLS credential reload. It is used for
- *  experimental purpose for now and subject to change. */
-typedef struct grpc_tls_credential_reload_config
-    grpc_tls_credential_reload_config;
-
 /** Config for TLS server authorization check. It is used for
  *  experimental purpose for now and subject to change. */
 typedef struct grpc_tls_server_authorization_check_config
     grpc_tls_server_authorization_check_config;
 
-/** TLS credentials options. It is used for
- *  experimental purpose for now and subject to change. */
+/**
+ * A struct that can be specified by callers to configure underlying TLS
+ * behaviors. It is used for experimental purpose for now and subject to change.
+ */
 typedef struct grpc_tls_credentials_options grpc_tls_credentials_options;
 
-/** Create an empty TLS credentials options. It is used for
- *  experimental purpose for now and subject to change. */
+/**
+ * A struct provides ways to gain credential data that will be used in the TLS
+ * handshake. It is used for experimental purpose for now and subject to change.
+ */
+typedef struct grpc_tls_certificate_provider grpc_tls_certificate_provider;
+
+/**
+ * A struct that stores the credential data presented to the peer in handshake
+ * to show local identity. It is used for experimental purpose for now and
+ * subject to change.
+ */
+typedef struct grpc_tls_identity_pairs grpc_tls_identity_pairs;
+
+/**
+ * Creates a grpc_tls_identity_pairs that stores a list of identity credential
+ * data, including identity private key and identity certificate chain. It is
+ * used for experimental purpose for now and subject to change.
+ */
+GRPCAPI grpc_tls_identity_pairs* grpc_tls_identity_pairs_create();
+
+/**
+ * Adds a identity private key and a identity certificate chain to
+ * grpc_tls_identity_pairs. This function will make an internal copy of
+ * |private_key| and |cert_chain|. It is used for experimental purpose for now
+ * and subject to change.
+ */
+GRPCAPI void grpc_tls_identity_pairs_add_pair(grpc_tls_identity_pairs* pairs,
+                                              const char* private_key,
+                                              const char* cert_chain);
+
+/**
+ * Destroys a grpc_tls_identity_pairs object. If this object is passed to a
+ * provider initiation function, the ownership is transferred so this function
+ * doesn't need to be called. Otherwise the creator of the
+ * grpc_tls_identity_pairs object is responsible for its destruction. It is
+ * used for experimental purpose for now and subject to change.
+ */
+GRPCAPI void grpc_tls_identity_pairs_destroy(grpc_tls_identity_pairs* pairs);
+
+/**
+ * Creates a grpc_tls_certificate_provider that will load credential data from
+ * static string during initialization. This provider will always return the
+ * same cert data for all cert names.
+ * root_certificate and pem_key_cert_pairs can be nullptr, indicating the
+ * corresponding credential data is not needed.
+ * This function will make a copy of |root_certificate|.
+ * The ownership of |pem_key_cert_pairs| is transferred.
+ * It is used for experimental purpose for now and subject to change.
+ */
+GRPCAPI grpc_tls_certificate_provider*
+grpc_tls_certificate_provider_static_data_create(
+    const char* root_certificate, grpc_tls_identity_pairs* pem_key_cert_pairs);
+
+/**
+ * Creates a grpc_tls_certificate_provider that will watch the credential
+ * changes on the file system. This provider will always return the up-to-date
+ * cert data for all the cert names callers set through
+ * |grpc_tls_credentials_options|. Note that this API only supports one key-cert
+ * file and hence one set of identity key-cert pair, so SNI(Server Name
+ * Indication) is not supported.
+ * - private_key_path is the file path of the private key. This must be set if
+ *   |identity_certificate_path| is set. Otherwise, it could be null if no
+ *   identity credentials are needed.
+ * - identity_certificate_path is the file path of the identity certificate
+ *   chain. This must be set if |private_key_path| is set. Otherwise, it could
+ *   be null if no identity credentials are needed.
+ * - root_cert_path is the file path to the root certificate bundle. This
+ *   may be null if no root certs are needed.
+ * - refresh_interval_sec is the refreshing interval that we will check the
+ *   files for updates.
+ * It does not take ownership of parameters.
+ * It is used for experimental purpose for now and subject to change.
+ */
+GRPCAPI grpc_tls_certificate_provider*
+grpc_tls_certificate_provider_file_watcher_create(
+    const char* private_key_path, const char* identity_certificate_path,
+    const char* root_cert_path, unsigned int refresh_interval_sec);
+
+/**
+ * Releases a grpc_tls_certificate_provider object. The creator of the
+ * grpc_tls_certificate_provider object is responsible for its release. It is
+ * used for experimental purpose for now and subject to change.
+ */
+GRPCAPI void grpc_tls_certificate_provider_release(
+    grpc_tls_certificate_provider* provider);
+
+/**
+ * Creates an grpc_tls_credentials_options.
+ * It is used for experimental purpose for now and subject to change.
+ */
 GRPCAPI grpc_tls_credentials_options* grpc_tls_credentials_options_create(void);
 
-/** Set grpc_ssl_client_certificate_request_type field in credentials options
-    with the provided type. options should not be NULL.
-    It returns 1 on success and 0 on failure. It is used for
-    experimental purpose for now and subject to change. */
-GRPCAPI int grpc_tls_credentials_options_set_cert_request_type(
+/**
+ * Sets the options of whether to request and verify client certs. This should
+ * be called only on the server side. It returns 1 on success and 0 on failure.
+ * It is used for experimental purpose for now and subject to change.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_cert_request_type(
     grpc_tls_credentials_options* options,
     grpc_ssl_client_certificate_request_type type);
 
-/** Set grpc_tls_server_verification_option field in credentials options
-    with the provided server_verification_option. options should not be NULL.
-    This should be called only on the client side.
-    If grpc_tls_server_verification_option is not
-    GRPC_TLS_SERVER_VERIFICATION, use of a customer server
-    authorization check (grpc_tls_server_authorization_check_config)
-    will be mandatory.
-    It returns 1 on success and 0 on failure. It is used for
-    experimental purpose for now and subject to change. */
-GRPCAPI int grpc_tls_credentials_options_set_server_verification_option(
+/**
+ * Sets the options of whether to choose certain checks, e.g. certificate check,
+ * hostname check, etc. This should be called only on the client side. If
+ * |server_verification_option| is not GRPC_TLS_SERVER_VERIFICATION, use of a
+ * custom authorization check (grpc_tls_server_authorization_check_config) is
+ * mandatory. It returns 1 on success and 0 on failure. It is used for
+ * experimental purpose for now and subject to change.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_server_verification_option(
     grpc_tls_credentials_options* options,
     grpc_tls_server_verification_option server_verification_option);
 
-/** Set grpc_tls_key_materials_config field in credentials options
-    with the provided config struct whose ownership is transferred.
-    Both parameters should not be NULL.
-    It returns 1 on success and 0 on failure. It is used for
-    experimental purpose for now and subject to change. */
-GRPCAPI int grpc_tls_credentials_options_set_key_materials_config(
-    grpc_tls_credentials_options* options,
-    grpc_tls_key_materials_config* config);
-
-/** Set grpc_tls_credential_reload_config field in credentials options
-    with the provided config struct whose ownership is transferred.
-    Both parameters should not be NULL.
-    It returns 1 on success and 0 on failure. It is used for
-    experimental purpose for now and subject to change. */
-GRPCAPI int grpc_tls_credentials_options_set_credential_reload_config(
-    grpc_tls_credentials_options* options,
-    grpc_tls_credential_reload_config* config);
-
-/** Set grpc_tls_server_authorization_check_config field in credentials options
-    with the provided config struct whose ownership is transferred.
-    Both parameters should not be NULL.
-    It returns 1 on success and 0 on failure. It is used for
-    experimental purpose for now and subject to change. */
-GRPCAPI int grpc_tls_credentials_options_set_server_authorization_check_config(
+/**
+ * Sets the credential provider in the options.
+ * The |options| will implicitly take a new ref to the |provider|.
+ * It returns 1 on success and 0 on failure.
+ * It is used for experimental purpose for now and subject to change.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_certificate_provider(
     grpc_tls_credentials_options* options,
-    grpc_tls_server_authorization_check_config* config);
+    grpc_tls_certificate_provider* provider);
 
-/** --- TLS key materials config. ---
-    It is used for experimental purpose for now and subject to change. */
+/**
+ * If set, gRPC stack will keep watching the root certificates with
+ * name |root_cert_name|. It returns 1 on success and 0 on failure. It is used
+ * for experimental purpose for now and subject to change.
+ */
+GRPCAPI void grpc_tls_credentials_options_watch_root_certs(
+    grpc_tls_credentials_options* options);
 
-/** Create an empty grpc_tls_key_materials_config instance.
- *  It is used for experimental purpose for now and subject to change. */
-GRPCAPI grpc_tls_key_materials_config* grpc_tls_key_materials_config_create(
-    void);
-
-/** Set grpc_tls_key_materials_config instance with provided a TLS certificate.
-    It's valid for the caller to provide nullptr pem_root_certs, in which case
-    the gRPC-provided root cert will be used. pem_key_cert_pairs should not be
-    NULL.
-    The ownerships of |pem_root_certs| and |pem_key_cert_pairs| remain with the
-    caller.
-    It returns 1 on success and 0 on failure. It is used for experimental
-    purpose for now and subject to change.
+/**
+ * Sets the name of the root certificates being watched.
+ * If not set, We will use a default empty string as the root certificate name.
+ * It is used for experimental purpose for now and subject to change.
  */
-GRPCAPI int grpc_tls_key_materials_config_set_key_materials(
-    grpc_tls_key_materials_config* config, const char* pem_root_certs,
-    const grpc_ssl_pem_key_cert_pair** pem_key_cert_pairs,
-    size_t num_key_cert_pairs);
+GRPCAPI void grpc_tls_credentials_options_set_root_cert_name(
+    grpc_tls_credentials_options* options, const char* root_cert_name);
 
-/** Set grpc_tls_key_materials_config instance with a provided version number,
-    which is used to keep track of the version of key materials.
-    It returns 1 on success and 0 on failure. It is used for
-    experimental purpose for now and subject to change.
+/**
+ * If set, gRPC stack will keep watching the identity key-cert pairs
+ * with name |identity_cert_name|. It returns 1 on success and 0 on failure. It
+ * is used for experimental purpose for now and subject to change.
  */
-GRPCAPI int grpc_tls_key_materials_config_set_version(
-    grpc_tls_key_materials_config* config, int version);
+GRPCAPI void grpc_tls_credentials_options_watch_identity_key_cert_pairs(
+    grpc_tls_credentials_options* options);
 
-/** Get the version number of a grpc_tls_key_materials_config instance.
-    It returns the version number on success and -1 on failure.
-    It is used for experimental purpose for now and subject to change.
+/**
+ * Sets the name of the identity certificates being watched.
+ * If not set, We will use a default empty string as the identity certificate
+ * name. It is used for experimental purpose for now and subject to change.
  */
-GRPCAPI int grpc_tls_key_materials_config_get_version(
-    grpc_tls_key_materials_config* config);
-
-/** --- TLS credential reload config. ---
-    It is used for experimental purpose for now and subject to change.*/
-
-typedef struct grpc_tls_credential_reload_arg grpc_tls_credential_reload_arg;
-
-/** A callback function provided by gRPC to handle the result of credential
-    reload. It is used when schedule API is implemented asynchronously and
-    serves to bring the control back to grpc C core. It is used for
-    experimental purpose for now and subject to change. */
-typedef void (*grpc_tls_on_credential_reload_done_cb)(
-    grpc_tls_credential_reload_arg* arg);
-
-/** A struct containing all information necessary to schedule/cancel a
-    credential reload request.
-    - cb and cb_user_data represent a gRPC-provided
-      callback and an argument passed to it.
-    - key_materials_config is an in/output parameter containing currently
-      used/newly reloaded credentials. If credential reload does not result in
-      a new credential, key_materials_config should not be modified. The same
-      key_materials_config object can be updated if new key materials is
-      available.
-    - status and error_details are used to hold information about
-      errors occurred when a credential reload request is scheduled/cancelled.
-    - config is a pointer to the unique grpc_tls_credential_reload_config
-      instance that this argument corresponds to.
-    - context is a pointer to a wrapped language implementation of this
-      grpc_tls_credential_reload_arg instance.
-    - destroy_context is a pointer to a caller-provided method that cleans
-      up any data associated with the context pointer.
-    It is used for experimental purposes for now and subject to change.
-*/
-struct grpc_tls_credential_reload_arg {
-  grpc_tls_on_credential_reload_done_cb cb;
-  void* cb_user_data;
-  grpc_tls_key_materials_config* key_materials_config;
-  grpc_ssl_certificate_config_reload_status status;
-  grpc_tls_error_details* error_details;
-  grpc_tls_credential_reload_config* config;
-  void* context;
-  void (*destroy_context)(void* ctx);
-};
+GRPCAPI void grpc_tls_credentials_options_set_identity_cert_name(
+    grpc_tls_credentials_options* options, const char* identity_cert_name);
 
-/** Create a grpc_tls_credential_reload_config instance.
-    - config_user_data is config-specific, read-only user data
-      that works for all channels created with a credential using the config.
-    - schedule is a pointer to an application-provided callback used to invoke
-      credential reload API. The implementation of this method has to be
-      non-blocking, but can be performed synchronously or asynchronously.
-      1) If processing occurs synchronously, it populates
-      arg->key_materials_config, arg->status, and arg->error_details
-      and returns zero.
-      2) If processing occurs asynchronously, it returns a non-zero value.
-      The application then invokes arg->cb when processing is completed. Note
-      that arg->cb cannot be invoked before schedule API returns.
-    - cancel is a pointer to an application-provided callback used to cancel
-      a credential reload request scheduled via an asynchronous schedule API.
-      arg is used to pinpoint an exact reloading request to be cancelled.
-      The operation may not have any effect if the request has already been
-      processed.
-    - destruct is a pointer to an application-provided callback used to clean up
-      any data associated with the config.
-    It is used for experimental purpose for now and subject to change.
-*/
-GRPCAPI grpc_tls_credential_reload_config*
-grpc_tls_credential_reload_config_create(
-    const void* config_user_data,
-    int (*schedule)(void* config_user_data,
-                    grpc_tls_credential_reload_arg* arg),
-    void (*cancel)(void* config_user_data, grpc_tls_credential_reload_arg* arg),
-    void (*destruct)(void* config_user_data));
+/**
+ * Sets the configuration for a custom authorization check performed at the end
+ * of the handshake. The |options| will implicitly take a new ref to the
+ * |config|. It returns 1 on success and 0 on failure. It is used for
+ * experimental purpose for now and subject to change.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_server_authorization_check_config(
+    grpc_tls_credentials_options* options,
+    grpc_tls_server_authorization_check_config* config);
 
 /** --- TLS server authorization check config. ---
  *  It is used for experimental purpose for now and subject to change. */
@@ -944,6 +950,8 @@ typedef void (*grpc_tls_on_server_authorization_check_done_cb)(
    - target_name is the name of an endpoint the channel is connecting to.
    - peer_cert represents a complete certificate chain including both
      signing and leaf certificates.
+   - \a subject_alternative_names is an array of size
+     \a subject_alternative_names_size consisting of pointers to strings.
    - status and error_details contain information
      about errors occurred when a server authorization check request is
      scheduled/cancelled.
@@ -963,6 +971,8 @@ struct grpc_tls_server_authorization_check_arg {
   const char* target_name;
   const char* peer_cert;
   const char* peer_cert_full_chain;
+  char** subject_alternative_names;
+  size_t subject_alternative_names_size;
   grpc_status_code status;
   grpc_tls_error_details* error_details;
   grpc_tls_server_authorization_check_config* config;
@@ -1000,34 +1010,75 @@ grpc_tls_server_authorization_check_config_create(
     void (*destruct)(void* config_user_data));
 
 /**
- * This method creates a TLS channel credential object.
- * It takes ownership of the options parameter. The security level
- * of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
- *
- * - options: grpc TLS credentials options instance.
- *
- * It returns the created credential object.
- *
- * It is used for experimental purpose for now and subject
- * to change.
+ * Releases a grpc_tls_server_authorization_check_config object. The creator of
+ * the grpc_tls_server_authorization_check_config object is responsible for its
+ * release. It is used for experimental purpose for now and subject to change.
  */
+GRPCAPI void grpc_tls_server_authorization_check_config_release(
+    grpc_tls_server_authorization_check_config* config);
 
+/**
+ * Creates a TLS channel credential object based on the
+ * grpc_tls_credentials_options specified by callers. The
+ * grpc_channel_credentials will take the ownership of the |options|. The
+ * security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY. It
+ * is used for experimental purpose for now and subject to change.
+ */
 grpc_channel_credentials* grpc_tls_credentials_create(
     grpc_tls_credentials_options* options);
 
 /**
- * This method creates a TLS server credential object.
- * It takes ownership of the options parameter.
+ * Creates a TLS server credential object based on the
+ * grpc_tls_credentials_options specified by callers. The
+ * grpc_server_credentials will take the ownership of the |options|. It
+ * is used for experimental purpose for now and subject to change.
+ */
+grpc_server_credentials* grpc_tls_server_credentials_create(
+    grpc_tls_credentials_options* options);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * This method creates an insecure channel credentials object.
+ */
+grpc_channel_credentials* grpc_insecure_credentials_create();
+
+/**
+ * EXPERIMENTAL API - Subject to change
  *
- * - options: grpc TLS credentials options instance.
+ * This method creates an insecure server credentials object.
+ */
+grpc_server_credentials* grpc_insecure_server_credentials_create();
+
+/**
+ * EXPERIMENTAL API - Subject to change
  *
- * It returns the created credential object.
+ * This method creates an xDS channel credentials object.
  *
- * It is used for experimental purpose for now and subject
- * to change.
+ * Creating a channel with credentials of this type indicates that the channel
+ * should get credentials configuration from the xDS control plane.
+ *
+ * \a fallback_credentials are used if the channel target does not have the
+ * 'xds:///' scheme or if the xDS control plane does not provide information on
+ * how to fetch credentials dynamically. Does NOT take ownership of the \a
+ * fallback_credentials. (Internally takes a ref to the object.)
  */
-grpc_server_credentials* grpc_tls_server_credentials_create(
-    grpc_tls_credentials_options* options);
+GRPCAPI grpc_channel_credentials* grpc_xds_credentials_create(
+    grpc_channel_credentials* fallback_credentials);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * This method creates an xDS server credentials object.
+ *
+ * \a fallback_credentials are used if the xDS control plane does not provide
+ * information on how to fetch credentials dynamically.
+ *
+ * Does NOT take ownership of the \a fallback_credentials. (Internally takes
+ * a ref to the object.)
+ */
+GRPCAPI grpc_server_credentials* grpc_xds_server_credentials_create(
+    grpc_server_credentials* fallback_credentials);
 
 #ifdef __cplusplus
 }