grpc 1.15.0 → 1.30.0

data/include/grpc/grpc.h

@@ -73,10 +73,11 @@ GRPCAPI void grpc_init(void);
     Before it's called, there should haven been a matching invocation to
     grpc_init().
 
-    No memory is used by grpc after this call returns, nor are any instructions
-    executing within the grpc library.
-    Prior to calling, all application owned grpc objects must have been
-    destroyed. */
+    The last call to grpc_shutdown will initiate cleaning up of grpc library
+    internals, which can happen in another thread. Once the clean-up is done,
+    no memory is used by grpc, nor are any instructions executing within the
+    grpc library.  Prior to calling, all application owned grpc objects must
+    have been destroyed. */
 GRPCAPI void grpc_shutdown(void);
 
 /** EXPERIMENTAL. Returns 1 if the grpc library has been initialized.
@@ -85,6 +86,10 @@ 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. */
+GRPCAPI void grpc_shutdown_blocking(void);
+
 /** Return a string representing the current version of grpc */
 GRPCAPI const char* grpc_version_string(void);
 
@@ -111,7 +116,8 @@ GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_pluck(
     of GRPC_CQ_CALLBACK and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING.
     This function is experimental. */
 GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_callback(
-    void* shutdown_callback, void* reserved);
+    grpc_experimental_completion_queue_functor* shutdown_callback,
+    void* reserved);
 
 /** Create a completion queue */
 GRPCAPI grpc_completion_queue* grpc_completion_queue_create(
@@ -218,7 +224,9 @@ GRPCAPI grpc_call* grpc_channel_create_call(
 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. */
+/** Pre-register a method/host pair on a channel.
+    method and host are not owned and must remain alive while the channel is
+    alive. */
 GRPCAPI void* grpc_channel_register_call(grpc_channel* channel,
                                          const char* method, const char* host,
                                          void* reserved);
@@ -247,10 +255,13 @@ GRPCAPI void* grpc_call_arena_alloc(grpc_call* call, size_t size);
     appropriate to call grpc_completion_queue_next or
     grpc_completion_queue_pluck consequent to the failed grpc_call_start_batch
     call.
+    If a call to grpc_call_start_batch with an empty batch returns
+    GRPC_CALL_OK, the tag is put in the completion queue immediately.
     THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment
     needs to be synchronized. As an optimization, you may synchronize batches
     containing just send operations independently from batches containing just
-    receive operations. */
+    receive operations. Access to grpc_call_start_batch with an empty batch is
+    thread-compatible. */
 GRPCAPI grpc_call_error grpc_call_start_batch(grpc_call* call,
                                               const grpc_op* ops, size_t nops,
                                               void* tag, void* reserved);
@@ -314,14 +325,14 @@ GRPCAPI void grpc_channel_destroy(grpc_channel* channel);
    If a grpc_call fails, it's guaranteed that no change to the call state
    has been made. */
 
-/** Called by clients to cancel an RPC on the server.
+/** Cancel an RPC.
     Can be called multiple times, from any thread.
     THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status
     are thread-safe, and can be called at any point before grpc_call_unref
     is called.*/
 GRPCAPI grpc_call_error grpc_call_cancel(grpc_call* call, void* reserved);
 
-/** Called by clients to cancel an RPC on the server.
+/** Cancel an RPC.
     Can be called multiple times, from any thread.
     If a status has not been received for the call, set it to the status code
     and description passed in.
@@ -499,10 +510,29 @@ GRPCAPI const grpc_arg_pointer_vtable* grpc_resource_quota_arg_vtable(void);
    The returned string is allocated and must be freed by the application. */
 GRPCAPI char* grpc_channelz_get_top_channels(intptr_t start_channel_id);
 
+/* Gets all servers that exist in the process. */
+GRPCAPI char* grpc_channelz_get_servers(intptr_t start_server_id);
+
+/* Returns a single Server, or else a NOT_FOUND code. */
+GRPCAPI char* grpc_channelz_get_server(intptr_t server_id);
+
+/* Gets all server sockets that exist in the server. */
+GRPCAPI char* grpc_channelz_get_server_sockets(intptr_t server_id,
+                                               intptr_t start_socket_id,
+                                               intptr_t max_results);
+
 /* Returns a single Channel, or else a NOT_FOUND code. The returned string
    is allocated and must be freed by the application. */
 GRPCAPI char* grpc_channelz_get_channel(intptr_t channel_id);
 
+/* Returns a single Subchannel, or else a NOT_FOUND code. The returned string
+   is allocated and must be freed by the application. */
+GRPCAPI char* grpc_channelz_get_subchannel(intptr_t subchannel_id);
+
+/* Returns a single Socket, or else a NOT_FOUND code. The returned string
+   is allocated and must be freed by the application. */
+GRPCAPI char* grpc_channelz_get_socket(intptr_t socket_id);
+
 #ifdef __cplusplus
 }
 #endif

data/include/grpc/grpc_posix.h

@@ -52,14 +52,6 @@ GRPCAPI grpc_channel* grpc_insecure_channel_create_from_fd(
 GRPCAPI void grpc_server_add_insecure_channel_from_fd(grpc_server* server,
                                                       void* reserved, int fd);
 
-/** GRPC Core POSIX library may internally use signals to optimize some work.
-   The library uses (SIGRTMIN + 6) signal by default. Use this API to instruct
-   the library to use a different signal i.e 'signum' instead.
-   Note:
-   - To prevent GRPC library from using any signals, pass a 'signum' of -1
-   - This API is optional but if called, it MUST be called before grpc_init() */
-GRPCAPI void grpc_use_signal(int signum);
-
 #ifdef __cplusplus
 }
 #endif

data/include/grpc/grpc_security.h

@@ -132,7 +132,8 @@ 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. */
+   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);
 
 /** Callback for getting the SSL roots override from the application.
@@ -163,6 +164,28 @@ typedef struct {
   const char* cert_chain;
 } grpc_ssl_pem_key_cert_pair;
 
+/** Deprecated in favor of grpc_ssl_verify_peer_options. It will be removed
+  after all of its call sites are migrated to grpc_ssl_verify_peer_options.
+  Object that holds additional peer-verification options on a secure
+  channel. */
+typedef struct {
+  /** If non-NULL this callback will be invoked with the expected
+     target_name, the peer's certificate (in PEM format), and whatever
+     userdata pointer is set below. If a non-zero value is returned by this
+     callback then it is treated as a verification failure. Invocation of
+     the callback is blocking, so any implementation should be light-weight.
+     */
+  int (*verify_peer_callback)(const char* target_name, const char* peer_pem,
+                              void* userdata);
+  /** Arbitrary userdata that will be passed as the last argument to
+     verify_peer_callback. */
+  void* verify_peer_callback_userdata;
+  /** A destruct callback that will be invoked when the channel is being
+     cleaned up. The userdata argument will be passed to it. The intent is
+     to perform any cleanup associated with that userdata. */
+  void (*verify_peer_destruct)(void* userdata);
+} verify_peer_options;
+
 /** Object that holds additional peer-verification options on a secure
    channel. */
 typedef struct {
@@ -181,9 +204,12 @@ typedef struct {
      cleaned up. The userdata argument will be passed to it. The intent is
      to perform any cleanup associated with that userdata. */
   void (*verify_peer_destruct)(void* userdata);
-} verify_peer_options;
+} grpc_ssl_verify_peer_options;
 
-/** Creates an SSL credentials object.
+/** Deprecated in favor of grpc_ssl_server_credentials_create_ex. It will be
+   removed after all of its call sites are migrated to
+   grpc_ssl_server_credentials_create_ex. Creates an SSL credentials object.
+   The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
    - pem_root_certs is the NULL-terminated string containing the PEM encoding
      of the server root certificates. If this parameter is NULL, the
      implementation will first try to dereference the file pointed by the
@@ -191,6 +217,15 @@ typedef struct {
      try to get the roots set by grpc_override_ssl_default_roots. Eventually,
      if all these fail, it will try to get the roots from a well-known place on
      disk (in the grpc install directory).
+
+     gRPC has implemented root cache if the underlying OpenSSL library supports
+     it. The gRPC root certificates cache is only applicable on the default
+     root certificates, which is used when this parameter is nullptr. If user
+     provides their own pem_root_certs, when creating an SSL credential object,
+     gRPC would not be able to cache it, and each subchannel will generate a
+     copy of the root store. So it is recommended to avoid providing large room
+     pem with pem_root_certs parameter to avoid excessive memory consumption,
+     particularly on mobile platforms such as iOS.
    - pem_key_cert_pair is a pointer on the object containing client's private
      key and certificate chain. This parameter can be NULL if the client does
      not have such a key/cert pair.
@@ -205,6 +240,38 @@ GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create(
     const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pair,
     const verify_peer_options* verify_options, void* reserved);
 
+/* Creates an SSL credentials object.
+   The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
+   - pem_root_certs is the NULL-terminated string containing the PEM encoding
+     of the server root certificates. If this parameter is NULL, the
+     implementation will first try to dereference the file pointed by the
+     GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails,
+     try to get the roots set by grpc_override_ssl_default_roots. Eventually,
+     if all these fail, it will try to get the roots from a well-known place on
+     disk (in the grpc install directory).
+
+     gRPC has implemented root cache if the underlying OpenSSL library supports
+     it. The gRPC root certificates cache is only applicable on the default
+     root certificates, which is used when this parameter is nullptr. If user
+     provides their own pem_root_certs, when creating an SSL credential object,
+     gRPC would not be able to cache it, and each subchannel will generate a
+     copy of the root store. So it is recommended to avoid providing large room
+     pem with pem_root_certs parameter to avoid excessive memory consumption,
+     particularly on mobile platforms such as iOS.
+   - pem_key_cert_pair is a pointer on the object containing client's private
+     key and certificate chain. This parameter can be NULL if the client does
+     not have such a key/cert pair.
+   - verify_options is an optional verify_peer_options object which holds
+     additional options controlling how peer certificates are verified. For
+     example, you can supply a callback which receives the peer's certificate
+     with which you can do additional verification. Can be NULL, in which
+     case verification will retain default behavior. Any settings in
+     verify_options are copied during this call, so the verify_options
+     object can be released afterwards. */
+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
@@ -217,7 +284,8 @@ typedef struct grpc_call_credentials grpc_call_credentials;
    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. */
+/** 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);
@@ -255,7 +323,7 @@ GRPCAPI grpc_call_credentials* grpc_google_refresh_token_credentials_create(
     const char* json_refresh_token, void* reserved);
 
 /** Creates an Oauth2 Access Token credentials with an access token that was
-   aquired by an out of band mechanism. */
+   acquired by an out of band mechanism. */
 GRPCAPI grpc_call_credentials* grpc_access_token_credentials_create(
     const char* access_token, void* reserved);
 
@@ -264,6 +332,31 @@ GRPCAPI grpc_call_credentials* grpc_google_iam_credentials_create(
     const char* authorization_token, const char* authority_selector,
     void* reserved);
 
+/** Options for creating STS Oauth Token Exchange credentials following the IETF
+   draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
+   Optional fields may be set to NULL or empty string. It is the responsibility
+   of the caller to ensure that the subject and actor tokens are refreshed on
+   disk at the specified paths. This API is used for experimental purposes for
+   now and may change in the future. */
+typedef struct {
+  const char* token_exchange_service_uri; /* Required. */
+  const char* resource;                   /* Optional. */
+  const char* audience;                   /* Optional. */
+  const char* scope;                      /* Optional. */
+  const char* requested_token_type;       /* Optional. */
+  const char* subject_token_path;         /* Required. */
+  const char* subject_token_type;         /* Required. */
+  const char* actor_token_path;           /* Optional. */
+  const char* actor_token_type;           /* Optional. */
+} grpc_sts_credentials_options;
+
+/** Creates an STS credentials following the STS Token Exchanged specifed in the
+   IETF draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
+   This API is used for experimental purposes for now and may change in the
+   future. */
+GRPCAPI grpc_call_credentials* grpc_sts_credentials_create(
+    const grpc_sts_credentials_options* options, void* reserved);
+
 /** Callback function to be called by the metadata credentials plugin
    implementation when the metadata is ready.
    - user_data is the opaque pointer that was passed in the get_metadata method
@@ -332,6 +425,10 @@ typedef struct {
       size_t* num_creds_md, grpc_status_code* status,
       const char** error_details);
 
+  /** Implements debug string of the given plugin. This method returns an
+   * allocated string that the caller needs to free using gpr_free() */
+  char* (*debug_string)(void* state);
+
   /** Destroys the plugin state. */
   void (*destroy)(void* state);
 
@@ -342,9 +439,11 @@ typedef struct {
   const char* type;
 } grpc_metadata_credentials_plugin;
 
-/** Creates a credentials object from a plugin. */
+/** Creates a credentials object from a plugin with a specified minimum security
+ * level. */
 GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin(
-    grpc_metadata_credentials_plugin plugin, void* reserved);
+    grpc_metadata_credentials_plugin plugin,
+    grpc_security_level min_security_level, void* reserved);
 
 /** --- Secure channel creation. --- */
 
@@ -426,7 +525,7 @@ GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create(
 /** Deprecated in favor of grpc_ssl_server_credentials_create_with_options.
    Same as grpc_ssl_server_credentials_create method except uses
    grpc_ssl_client_certificate_request_type enum to support more ways to
-   authenticate client cerificates.*/
+   authenticate client certificates.*/
 GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create_ex(
     const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs,
     size_t num_key_cert_pairs,
@@ -532,14 +631,14 @@ typedef struct grpc_alts_credentials_options grpc_alts_credentials_options;
  * It is used for experimental purpose for now and subject to change.
  */
 GRPCAPI grpc_alts_credentials_options*
-grpc_alts_credentials_client_options_create();
+grpc_alts_credentials_client_options_create(void);
 
 /**
  * This method creates a grpc ALTS credentials server options instance.
  * It is used for experimental purpose for now and subject to change.
  */
 GRPCAPI grpc_alts_credentials_options*
-grpc_alts_credentials_server_options_create();
+grpc_alts_credentials_server_options_create(void);
 
 /**
  * This method adds a target service account to grpc client's ALTS credentials
@@ -564,8 +663,9 @@ GRPCAPI void grpc_alts_credentials_options_destroy(
     grpc_alts_credentials_options* options);
 
 /**
- * This method creates an ALTS channel credential object. It is used for
- * experimental purpose for now and subject to change.
+ * This method creates an ALTS channel credential object. The security
+ * level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
+ * It is used for experimental purpose for now and subject to change.
  *
  * - options: grpc ALTS credentials options instance for client.
  *
@@ -588,8 +688,10 @@ GRPCAPI grpc_server_credentials* grpc_alts_server_credentials_create(
 /** --- Local channel/server credentials --- **/
 
 /**
- * This method creates a local channel credential object. It is used for
- * experimental purpose for now and subject to change.
+ * This method creates a local channel credential object. The security level
+ * of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY for UDS and
+ * GRPC_SECURITY_NONE for LOCAL_TCP. It is used for experimental purpose
+ * for now and subject to change.
  *
  * - type: local connection type
  *
@@ -609,6 +711,299 @@ GRPCAPI grpc_channel_credentials* grpc_local_credentials_create(
 GRPCAPI grpc_server_credentials* grpc_local_server_credentials_create(
     grpc_local_connect_type type);
 
+/** --- TLS channel/server credentials ---
+ * It is used for experimental purpose for now and subject to change. */
+
+/** Struct for indicating errors. It is used for
+ *  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. */
+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. */
+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(
+    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(
+    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(
+    grpc_tls_credentials_options* options,
+    grpc_tls_server_authorization_check_config* config);
+
+/** --- TLS key materials config. ---
+    It is used for experimental purpose for now and subject to change. */
+
+/** 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);
+
+/** 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.
+ */
+GRPCAPI int grpc_tls_key_materials_config_set_version(
+    grpc_tls_key_materials_config* config, int version);
+
+/** 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.
+ */
+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);
+};
+
+/** 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));
+
+/** --- TLS server authorization check config. ---
+ *  It is used for experimental purpose for now and subject to change. */
+
+typedef struct grpc_tls_server_authorization_check_arg
+    grpc_tls_server_authorization_check_arg;
+
+/** callback function provided by gRPC used to handle the result of server
+    authorization check. 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_server_authorization_check_done_cb)(
+    grpc_tls_server_authorization_check_arg* arg);
+
+/** A struct containing all information necessary to schedule/cancel a server
+    authorization check request.
+    - cb and cb_user_data represent a gRPC-provided callback and an argument
+      passed to it.
+    - success will store the result of server authorization check. That is,
+      if success returns a non-zero value, it means the authorization check
+      passes and if returning zero, it means the check fails.
+   - 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.
+   - status and error_details contain information
+     about errors occurred when a server authorization check request is
+     scheduled/cancelled.
+   - config is a pointer to the unique
+     grpc_tls_server_authorization_check_config instance that this argument
+     corresponds to.
+   - context is a pointer to a wrapped language implementation of this
+     grpc_tls_server_authorization_check_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 purpose for now and subject to change.
+*/
+struct grpc_tls_server_authorization_check_arg {
+  grpc_tls_on_server_authorization_check_done_cb cb;
+  void* cb_user_data;
+  int success;
+  const char* target_name;
+  const char* peer_cert;
+  const char* peer_cert_full_chain;
+  grpc_status_code status;
+  grpc_tls_error_details* error_details;
+  grpc_tls_server_authorization_check_config* config;
+  void* context;
+  void (*destroy_context)(void* ctx);
+};
+
+/** Create a grpc_tls_server_authorization_check_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
+      server authorization check 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->result,
+      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
+      server authorization check request scheduled via an asynchronous schedule
+      API. arg is used to pinpoint an exact check 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_server_authorization_check_config*
+grpc_tls_server_authorization_check_config_create(
+    const void* config_user_data,
+    int (*schedule)(void* config_user_data,
+                    grpc_tls_server_authorization_check_arg* arg),
+    void (*cancel)(void* config_user_data,
+                   grpc_tls_server_authorization_check_arg* arg),
+    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.
+ */
+
+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.
+ *
+ * - options: grpc TLS credentials options instance.
+ *
+ * It returns the created credential object.
+ *
+ * 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);
+
 #ifdef __cplusplus
 }
 #endif