grpc 1.30.0 → 1.46.3

data/include/grpc/grpc_security.h

@@ -119,22 +119,38 @@ 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_channel_credentials object. ---
+/** --- grpc_call_credentials object.
 
-   A channel credentials object represents a way to authenticate a client on a
-   channel.  */
+   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_channel_credentials grpc_channel_credentials;
+typedef struct grpc_call_credentials grpc_call_credentials;
 
-/** Releases a channel credentials object.
+/** Releases a call credentials object.
    The creator of the credentials object is responsible for its release. */
-GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials* creds);
+GRPCAPI void grpc_call_credentials_release(grpc_call_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 +288,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,
@@ -313,6 +319,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
@@ -390,6 +404,14 @@ typedef struct {
   void* reserved;
 } grpc_auth_metadata_context;
 
+/** Performs a deep copy from \a from to \a to. **/
+GRPCAPI void grpc_auth_metadata_context_copy(grpc_auth_metadata_context* from,
+                                             grpc_auth_metadata_context* to);
+
+/** Releases internal resources held by \a context. **/
+GRPCAPI void grpc_auth_metadata_context_reset(
+    grpc_auth_metadata_context* context);
+
 /** Maximum number of metadata entries returnable by a credentials plugin via
     a synchronous return. */
 #define GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX 4
@@ -445,30 +467,6 @@ GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin(
     grpc_metadata_credentials_plugin plugin,
     grpc_security_level min_security_level, void* reserved);
 
-/** --- Secure channel creation. --- */
-
-/** Creates a secure channel using the passed-in credentials. Additional
-    channel level configuration MAY be provided by grpc_channel_args, though
-    the expectation is that most clients will want to simply pass NULL. The
-    user data in 'args' need only live through the invocation of this function.
-    However, if any args of the 'pointer' type are passed, then the referenced
-    vtable must be maintained by the caller until grpc_channel_destroy
-    terminates. See grpc_channel_args definition for more on this. */
-GRPCAPI grpc_channel* grpc_secure_channel_create(
-    grpc_channel_credentials* creds, const char* target,
-    const grpc_channel_args* args, void* reserved);
-
-/** --- grpc_server_credentials object. ---
-
-   A server credentials object represents a way to authenticate a server.  */
-
-typedef struct grpc_server_credentials grpc_server_credentials;
-
-/** Releases a server_credentials object.
-   The creator of the server_credentials object is responsible for its release.
-   */
-GRPCAPI void grpc_server_credentials_release(grpc_server_credentials* creds);
-
 /** Server certificate config object holds the server's public certificates and
    associated private keys, as well as any CA certificates needed for client
    certificate validation (if applicable). Create using
@@ -566,15 +564,6 @@ GRPCAPI grpc_server_credentials*
 grpc_ssl_server_credentials_create_with_options(
     grpc_ssl_server_credentials_options* options);
 
-/** --- Server-side secure ports. --- */
-
-/** Add a HTTP2 over an encrypted link over tcp listener.
-   Returns bound port number on success, 0 on failure.
-   REQUIRES: server not started */
-GRPCAPI int grpc_server_add_secure_http2_port(grpc_server* server,
-                                              const char* addr,
-                                              grpc_server_credentials* creds);
-
 /** --- Call specific credentials. --- */
 
 /** Sets a credentials to a call. Can only be called on the client side before
@@ -714,296 +703,555 @@ GRPCAPI grpc_server_credentials* grpc_local_server_credentials_create(
 /** --- 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;
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * A struct that can be specified by callers to configure underlying TLS
+ * behaviors.
+ */
+typedef struct grpc_tls_credentials_options grpc_tls_credentials_options;
 
-/** 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;
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * A struct provides ways to gain credential data that will be used in the TLS
+ * handshake.
+ */
+typedef struct grpc_tls_certificate_provider grpc_tls_certificate_provider;
 
-/** 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;
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * A struct that stores the credential data presented to the peer in handshake
+ * to show local identity.
+ */
+typedef struct grpc_tls_identity_pairs grpc_tls_identity_pairs;
 
-/** 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;
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * Creates a grpc_tls_identity_pairs that stores a list of identity credential
+ * data, including identity private key and identity certificate chain.
+ */
+GRPCAPI grpc_tls_identity_pairs* grpc_tls_identity_pairs_create();
 
-/** 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;
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * 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|.
+ */
+GRPCAPI void grpc_tls_identity_pairs_add_pair(grpc_tls_identity_pairs* pairs,
+                                              const char* private_key,
+                                              const char* cert_chain);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * 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.
+ */
+GRPCAPI void grpc_tls_identity_pairs_destroy(grpc_tls_identity_pairs* pairs);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * 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.
+ */
+GRPCAPI grpc_tls_certificate_provider*
+grpc_tls_certificate_provider_static_data_create(
+    const char* root_certificate, grpc_tls_identity_pairs* pem_key_cert_pairs);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * 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.
+ */
+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);
 
-/** Create an empty TLS credentials options. It is used for
- *  experimental purpose for now and subject to change. */
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * Releases a grpc_tls_certificate_provider object. The creator of the
+ * grpc_tls_certificate_provider object is responsible for its release.
+ */
+GRPCAPI void grpc_tls_certificate_provider_release(
+    grpc_tls_certificate_provider* provider);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * Creates an grpc_tls_credentials_options.
+ */
 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(
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * Sets the credential provider in the options.
+ * The |options| will implicitly take a new ref to the |provider|.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_certificate_provider(
     grpc_tls_credentials_options* options,
-    grpc_ssl_client_certificate_request_type type);
+    grpc_tls_certificate_provider* provider);
 
-/** 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(
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * If set, gRPC stack will keep watching the root certificates with
+ * name |root_cert_name|.
+ * If this is not set on the client side, we will use the root certificates
+ * stored in the default system location, since client side must provide root
+ * certificates in TLS.
+ * If this is not set on the server side, we will not watch any root certificate
+ * updates, and assume no root certificates needed for the server(single-side
+ * TLS). Default root certs on the server side is not supported.
+ */
+GRPCAPI void grpc_tls_credentials_options_watch_root_certs(
+    grpc_tls_credentials_options* options);
+
+/**
+ * EXPERIMENTAL API - 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.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_root_cert_name(
+    grpc_tls_credentials_options* options, const char* root_cert_name);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * If set, gRPC stack will keep watching the identity key-cert pairs
+ * with name |identity_cert_name|.
+ * This is required on the server side, and optional on the client side.
+ */
+GRPCAPI void grpc_tls_credentials_options_watch_identity_key_cert_pairs(
+    grpc_tls_credentials_options* options);
+
+/**
+ * EXPERIMENTAL API - 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.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_identity_cert_name(
+    grpc_tls_credentials_options* options, const char* identity_cert_name);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * Sets the options of whether to request and/or verify client certs. This shall
+ * only be called on the server side.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_cert_request_type(
     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);
+    grpc_ssl_client_certificate_request_type type);
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * If set, gRPC will read all hashed x.509 CRL files in the directory and
+ * enforce the CRL files on all TLS handshakes. Only supported for OpenSSL
+ * version > 1.1.
+ * It is used for experimental purpose for now and subject to change.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_crl_directory(
+    grpc_tls_credentials_options* options, const char* crl_directory);
 
-/** 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;
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * Sets the options of whether to verify server certs on the client side.
+ * Passing in a non-zero value indicates verifying the certs.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_verify_server_cert(
+    grpc_tls_credentials_options* options, int verify_server_cert);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * The read-only request information exposed in a verification call.
+ * Callers should not directly manage the ownership of it. We will make sure it
+ * is always available inside verify() or cancel() call, and will destroy the
+ * object at the end of custom verification.
+ */
+typedef struct grpc_tls_custom_verification_check_request {
+  /* The target name of the server when the client initiates the connection. */
+  /* This field will be nullptr if on the server side. */
   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));
+  /* The information contained in the certificate chain sent from the peer. */
+  struct peer_info {
+    /* The Common Name field on the peer leaf certificate. */
+    const char* common_name;
+    /* The list of Subject Alternative Names on the peer leaf certificate. */
+    struct san_names {
+      char** uri_names;
+      size_t uri_names_size;
+      char** dns_names;
+      size_t dns_names_size;
+      char** email_names;
+      size_t email_names_size;
+      char** ip_names;
+      size_t ip_names_size;
+    } san_names;
+    /* The raw peer leaf certificate. */
+    const char* peer_cert;
+    /* The raw peer certificate chain. Note that it is not always guaranteed to
+     * get the peer full chain. For more, please refer to
+     * GRPC_X509_PEM_CERT_CHAIN_PROPERTY_NAME defined in file
+     * grpc_security_constants.h.
+     * TODO(ZhenLian): Consider fixing this in the future. */
+    const char* peer_cert_full_chain;
+  } peer_info;
+} grpc_tls_custom_verification_check_request;
 
 /**
- * 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.
+ * EXPERIMENTAL API - Subject to change
  *
- * - options: grpc TLS credentials options instance.
+ * A callback function provided by gRPC as a parameter of the |verify| function
+ * in grpc_tls_certificate_verifier_external. If |verify| is expected to be run
+ * asynchronously, the implementer of |verify| will need to invoke this callback
+ * with |callback_arg| and proper verification status at the end to bring the
+ * control back to gRPC C core.
+ */
+typedef void (*grpc_tls_on_custom_verification_check_done_cb)(
+    grpc_tls_custom_verification_check_request* request, void* callback_arg,
+    grpc_status_code status, const char* error_details);
+
+/**
+ * EXPERIMENTAL API - Subject to change
  *
- * It returns the created credential object.
+ * The internal verifier type that will be used inside core.
+ */
+typedef struct grpc_tls_certificate_verifier grpc_tls_certificate_verifier;
+
+/**
+ * EXPERIMENTAL API - Subject to change
  *
- * It is used for experimental purpose for now and subject
- * to change.
+ * A struct containing all the necessary functions a custom external verifier
+ * needs to implement to be able to be converted to an internal verifier.
  */
+typedef struct grpc_tls_certificate_verifier_external {
+  void* user_data;
+  /**
+   * A function pointer containing the verification logic that will be
+   * performed after the TLS handshake is done. It could be processed
+   * synchronously or asynchronously.
+   * - If expected to be processed synchronously, the implementer should
+   *   populate the verification result through |sync_status| and
+   *   |sync_error_details|, and then return true.
+   * - If expected to be processed asynchronously, the implementer should return
+   *   false immediately, and then in the asynchronous thread invoke |callback|
+   *   with the verification result. The implementer MUST NOT invoke the async
+   *   |callback| in the same thread before |verify| returns, otherwise it can
+   *   lead to deadlocks.
+   *
+   * user_data: any argument that is passed in the user_data of
+   *            grpc_tls_certificate_verifier_external during construction time
+   *            can be retrieved later here.
+   * request: request information exposed to the function implementer.
+   * callback: the callback that the function implementer needs to invoke, if
+   *           return a non-zero value. It is usually invoked when the
+   *           asynchronous verification is done, and serves to bring the
+   *           control back to gRPC.
+   * callback_arg: A pointer to the internal ExternalVerifier instance. This is
+   *               mainly used as an argument in |callback|, if want to invoke
+   *               |callback| in async mode.
+   * sync_status: indicates if a connection should be allowed. This should only
+   *              be used if the verification check is done synchronously.
+   * sync_error_details: the error generated while verifying a connection. This
+   *                     should only be used if the verification check is done
+   *                     synchronously. the implementation must allocate the
+   *                     error string via gpr_malloc() or gpr_strdup().
+   * return: return 0 if |verify| is expected to be executed asynchronously,
+   *         otherwise return a non-zero value.
+   */
+  int (*verify)(void* user_data,
+                grpc_tls_custom_verification_check_request* request,
+                grpc_tls_on_custom_verification_check_done_cb callback,
+                void* callback_arg, grpc_status_code* sync_status,
+                char** sync_error_details);
+  /**
+   * A function pointer that cleans up the caller-specified resources when the
+   * verifier is still running but the whole connection got cancelled. This
+   * could happen when the verifier is doing some async operations, and the
+   * whole handshaker object got destroyed because of connection time limit is
+   * reached, or any other reasons. In such cases, function implementers might
+   * want to be notified, and properly clean up some resources.
+   *
+   * user_data: any argument that is passed in the user_data of
+   *            grpc_tls_certificate_verifier_external during construction time
+   *            can be retrieved later here.
+   * request: request information exposed to the function implementer. It will
+   *          be the same request object that was passed to verify(), and it
+   *          tells the cancel() which request to cancel.
+   */
+  void (*cancel)(void* user_data,
+                 grpc_tls_custom_verification_check_request* request);
+  /**
+   * A function pointer that does some additional destruction work when the
+   * verifier is destroyed. This is used when the caller wants to associate some
+   * objects to the lifetime of external_verifier, and destroy them when
+   * external_verifier got destructed. For example, in C++, the class containing
+   * user-specified callback functions should not be destroyed before
+   * external_verifier, since external_verifier will invoke them while being
+   * used.
+   * Note that the caller MUST delete the grpc_tls_certificate_verifier_external
+   * object itself in this function, otherwise it will cause memory leaks. That
+   * also means the user_data has to carries at least a self pointer, for the
+   * callers to later delete it in destruct().
+   *
+   * user_data: any argument that is passed in the user_data of
+   *            grpc_tls_certificate_verifier_external during construction time
+   *            can be retrieved later here.
+   */
+  void (*destruct)(void* user_data);
+} grpc_tls_certificate_verifier_external;
 
-grpc_channel_credentials* grpc_tls_credentials_create(
-    grpc_tls_credentials_options* options);
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * Converts an external verifier to an internal verifier.
+ * Note that we will not take the ownership of the external_verifier. Callers
+ * will need to delete external_verifier in its own destruct function.
+ */
+grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_external_create(
+    grpc_tls_certificate_verifier_external* external_verifier);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * Factory function for an internal verifier that will do the default hostname
+ * check.
+ */
+grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_host_name_create();
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * Releases a grpc_tls_certificate_verifier object. The creator of the
+ * grpc_tls_certificate_verifier object is responsible for its release.
+ */
+void grpc_tls_certificate_verifier_release(
+    grpc_tls_certificate_verifier* verifier);
 
 /**
- * This method creates a TLS server credential object.
- * It takes ownership of the options parameter.
+ * EXPERIMENTAL API - Subject to change
  *
- * - options: grpc TLS credentials options instance.
+ * Sets the verifier in options. The |options| will implicitly take a new ref to
+ * the |verifier|. If not set on the client side, we will verify server's
+ * certificates, and check the default hostname. If not set on the server side,
+ * we will verify client's certificates.
+ */
+void grpc_tls_credentials_options_set_certificate_verifier(
+    grpc_tls_credentials_options* options,
+    grpc_tls_certificate_verifier* verifier);
+
+/**
+ * EXPERIMENTAL API - Subject to change
  *
- * It returns the created credential object.
+ * Sets the options of whether to check the hostname of the peer on a per-call
+ * basis. This is usually used in a combination with virtual hosting at the
+ * client side, where each individual call on a channel can have a different
+ * host associated with it.
+ * This check is intended to verify that the host specified for the individual
+ * call is covered by the cert that the peer presented.
+ * The default is a non-zero value, which indicates performing such checks.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_check_call_host(
+    grpc_tls_credentials_options* options, int check_call_host);
+
+/**
+ * EXPERIMENTAL API - Subject to change
  *
- * It is used for experimental purpose for now and subject
- * to change.
+ * Performs the verification logic of an internal verifier.
+ * This is typically used when composing the internal verifiers as part of the
+ * custom verification.
+ * If |grpc_tls_certificate_verifier_verify| returns true, inspect the
+ * verification result through request->status and request->error_details.
+ * Otherwise, inspect through the parameter of |callback|.
+ */
+int grpc_tls_certificate_verifier_verify(
+    grpc_tls_certificate_verifier* verifier,
+    grpc_tls_custom_verification_check_request* request,
+    grpc_tls_on_custom_verification_check_done_cb callback, void* callback_arg,
+    grpc_status_code* sync_status, char** sync_error_details);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * Performs the cancellation logic of an internal verifier.
+ * This is typically used when composing the internal verifiers as part of the
+ * custom verification.
+ */
+void grpc_tls_certificate_verifier_cancel(
+    grpc_tls_certificate_verifier* verifier,
+    grpc_tls_custom_verification_check_request* request);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * 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.
+ */
+grpc_channel_credentials* grpc_tls_credentials_create(
+    grpc_tls_credentials_options* options);
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * 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|.
  */
 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.
+ */
+GRPCAPI grpc_channel_credentials* grpc_insecure_credentials_create();
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * This method creates an insecure server credentials object.
+ */
+GRPCAPI grpc_server_credentials* grpc_insecure_server_credentials_create();
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * This method creates an xDS channel credentials object.
+ *
+ * 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.)
+ */
+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);
+
+/**
+ * EXPERIMENTAL - Subject to change.
+ * An opaque type that is responsible for providing authorization policies to
+ * gRPC.
+ */
+typedef struct grpc_authorization_policy_provider
+    grpc_authorization_policy_provider;
+
+/**
+ * EXPERIMENTAL - Subject to change.
+ * Creates a grpc_authorization_policy_provider using gRPC authorization policy
+ * from static string.
+ * - authz_policy is the input gRPC authorization policy.
+ * - code is the error status code on failure. On success, it equals
+ *   GRPC_STATUS_OK.
+ * - error_details contains details about the error if any. If the
+ *   initialization is successful, it will be null. Caller must use gpr_free to
+ *   destroy this string.
+ */
+GRPCAPI grpc_authorization_policy_provider*
+grpc_authorization_policy_provider_static_data_create(
+    const char* authz_policy, grpc_status_code* code,
+    const char** error_details);
+
+/**
+ * EXPERIMENTAL - Subject to change.
+ * Creates a grpc_authorization_policy_provider by watching for gRPC
+ * authorization policy changes in filesystem.
+ * - authz_policy is the file path of gRPC authorization policy.
+ * - refresh_interval_sec is the amount of time the internal thread would wait
+ *   before checking for file updates.
+ * - code is the error status code on failure. On success, it equals
+ *   GRPC_STATUS_OK.
+ * - error_details contains details about the error if any. If the
+ *   initialization is successful, it will be null. Caller must use gpr_free to
+ *   destroy this string.
+ */
+GRPCAPI grpc_authorization_policy_provider*
+grpc_authorization_policy_provider_file_watcher_create(
+    const char* authz_policy_path, unsigned int refresh_interval_sec,
+    grpc_status_code* code, const char** error_details);
+
+/**
+ * EXPERIMENTAL - Subject to change.
+ * Releases grpc_authorization_policy_provider object. The creator of
+ * grpc_authorization_policy_provider is responsible for its release.
+ */
+GRPCAPI void grpc_authorization_policy_provider_release(
+    grpc_authorization_policy_provider* provider);
+
+/** --- TLS session key logging. ---
+ * Experimental API to control tls session key logging. Tls session key logging
+ * is expected to be used only for debugging purposes and never in production.
+ * Tls session key logging is only enabled when:
+ *  At least one grpc_tls_credentials_options object is assigned a tls session
+ *  key logging file path using the API specified below.
+ */
+
+/**
+ * EXPERIMENTAL API - Subject to change.
+ * Configures a grpc_tls_credentials_options object with tls session key
+ * logging capability. TLS channels using these credentials have tls session
+ * key logging enabled.
+ * - options is the grpc_tls_credentials_options object
+ * - path is a string pointing to the location where TLS session keys would be
+ *   stored.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_tls_session_key_log_file_path(
+    grpc_tls_credentials_options* options, const char* path);
+
 #ifdef __cplusplus
 }
 #endif