grpc 1.31.0.pre2 → 1.34.0

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. */

data/include/grpc/grpc_security.h

@@ -119,6 +119,18 @@ GRPCAPI void grpc_ssl_session_cache_destroy(grpc_ssl_session_cache* cache);
 GRPCAPI grpc_arg
 grpc_ssl_session_cache_create_channel_arg(grpc_ssl_session_cache* cache);
 
+/** --- grpc_call_credentials object.
+
+   A call credentials object represents a way to authenticate on a particular
+   call. These credentials can be composed with a channel credentials object
+   so that they are sent with every call on this channel.  */
+
+typedef struct grpc_call_credentials grpc_call_credentials;
+
+/** Releases a call credentials object.
+   The creator of the credentials object is responsible for its release. */
+GRPCAPI void grpc_call_credentials_release(grpc_call_credentials* creds);
+
 /** --- grpc_channel_credentials object. ---
 
    A channel credentials object represents a way to authenticate a client on a
@@ -133,8 +145,23 @@ GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials* creds);
 /** Creates default credentials to connect to a google gRPC service.
    WARNING: Do NOT use this credentials to connect to a non-google service as
    this could result in an oauth2 token leak. The security level of the
-   resulting connection is GRPC_PRIVACY_AND_INTEGRITY. */
-GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create(void);
+   resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
+
+   If specified, the supplied call credentials object will be attached to the
+   returned channel credentials object. The call_credentials object must remain
+   valid throughout the lifetime of the returned grpc_channel_credentials
+   object. It is expected that the call credentials object was generated
+   according to the Application Default Credentials mechanism and asserts the
+   identity of the default service account of the machine. Supplying any other
+   sort of call credential will result in undefined behavior, up to and
+   including the sudden and unexpected failure of RPCs.
+
+   If nullptr is supplied, the returned channel credentials object will use a
+   call credentials object based on the Application Default Credentials
+   mechanism.
+*/
+GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create(
+    grpc_call_credentials* call_credentials);
 
 /** Callback for getting the SSL roots override from the application.
    In case of success, *pem_roots_certs must be set to a NULL terminated string
@@ -272,24 +299,14 @@ GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create_ex(
     const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pair,
     const grpc_ssl_verify_peer_options* verify_options, void* reserved);
 
-/** --- grpc_call_credentials object.
-
-   A call credentials object represents a way to authenticate on a particular
-   call. These credentials can be composed with a channel credentials object
-   so that they are sent with every call on this channel.  */
-
-typedef struct grpc_call_credentials grpc_call_credentials;
-
-/** Releases a call credentials object.
-   The creator of the credentials object is responsible for its release. */
-GRPCAPI void grpc_call_credentials_release(grpc_call_credentials* creds);
-
 /** Creates a composite channel credentials object. The security level of
  * resulting connection is determined by channel_creds. */
 GRPCAPI grpc_channel_credentials* grpc_composite_channel_credentials_create(
     grpc_channel_credentials* channel_creds, grpc_call_credentials* call_creds,
     void* reserved);
 
+/** --- composite credentials. */
+
 /** Creates a composite call credentials object. */
 GRPCAPI grpc_call_credentials* grpc_composite_call_credentials_create(
     grpc_call_credentials* creds1, grpc_call_credentials* creds2,
@@ -726,183 +743,156 @@ 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);
+
+/**
+ * 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.
- */
-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);
+/**
+ * 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 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. */
@@ -983,34 +973,54 @@ 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
  *
- * - options: grpc TLS credentials options instance.
+ * This method creates an insecure channel credentials object.
+ */
+grpc_channel_credentials* grpc_insecure_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 an xDS
+ * 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);
 
 #ifdef __cplusplus
 }