#include <grpc/support/port_platform.h>#include <grpc/grpc.h>#include <grpc/grpc_security_constants.h>#include <grpc/status.h>
Go to the source code of this file.
Classes | |
| struct | grpc_auth_metadata_context |
| struct | grpc_auth_metadata_processor |
| struct | grpc_auth_property |
| struct | grpc_auth_property_iterator |
| struct | grpc_metadata_credentials_plugin |
| struct | grpc_ssl_pem_key_cert_pair |
| struct | grpc_ssl_verify_peer_options |
| struct | grpc_sts_credentials_options |
| struct | grpc_tls_certificate_verifier_external |
| struct | grpc_tls_custom_verification_check_request |
| struct | grpc_tls_custom_verification_check_request::peer_info |
| struct | grpc_tls_custom_verification_check_request::peer_info::san_names |
| struct | verify_peer_options |
Macros | |
| #define | GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX 4 |
Macro Definition Documentation
◆ GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX
| #define GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX 4 |
Maximum number of metadata entries returnable by a credentials plugin via a synchronous return.
Definition at line 417 of file grpc_security.h.
Typedef Documentation
◆ grpc_alts_credentials_options
| typedef struct grpc_alts_credentials_options grpc_alts_credentials_options |
— ALTS channel/server credentials — Main interface for ALTS credentials options. The options will contain information that will be passed from grpc to TSI layer such as RPC protocol versions. ALTS client (channel) and server credentials will have their own implementation of this interface. The APIs listed in this header are thread-compatible. It is used for experimental purpose for now and subject to change.
Definition at line 616 of file grpc_security.h.
◆ grpc_auth_context
| typedef struct grpc_auth_context grpc_auth_context |
— Authentication Context. —
Definition at line 34 of file grpc_security.h.
◆ grpc_auth_property
| typedef struct grpc_auth_property grpc_auth_property |
value, if not NULL, is guaranteed to be NULL terminated.
◆ grpc_auth_property_iterator
| typedef struct grpc_auth_property_iterator grpc_auth_property_iterator |
◆ grpc_authorization_policy_provider
EXPERIMENTAL - Subject to change. An opaque type that is responsible for providing authorization policies to gRPC.
Definition at line 1201 of file grpc_security.h.
◆ grpc_call_credentials
| typedef struct grpc_call_credentials grpc_call_credentials |
— 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.
Definition at line 128 of file grpc_security.h.
◆ grpc_credentials_plugin_metadata_cb
| typedef void(* grpc_credentials_plugin_metadata_cb) (void *user_data, const grpc_metadata *creds_md, size_t num_creds_md, grpc_status_code status, const char *error_details) |
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 of the grpc_metadata_credentials_plugin (see below).
- creds_md is an array of credentials metadata produced by the plugin. It may be set to NULL in case of an error.
- num_creds_md is the number of items in the creds_md array.
- status must be GRPC_STATUS_OK in case of success or another specific error code otherwise.
- error_details contains details about the error if any. In case of success it should be NULL and will be otherwise ignored.
Definition at line 385 of file grpc_security.h.
◆ grpc_process_auth_metadata_done_cb
| typedef void(* grpc_process_auth_metadata_done_cb) (void *user_data, const grpc_metadata *consumed_md, size_t num_consumed_md, const grpc_metadata *response_md, size_t num_response_md, grpc_status_code status, const char *error_details) |
— Auth Metadata Processing — Callback function that is called when the metadata processing is done.
- Consumed metadata will be removed from the set of metadata available on the call. consumed_md may be NULL if no metadata has been consumed.
- Response metadata will be set on the response. response_md may be NULL.
- status is GRPC_STATUS_OK for success or a specific status for an error. Common error status for auth metadata processing is either GRPC_STATUS_UNAUTHENTICATED in case of an authentication failure or GRPC_STATUS PERMISSION_DENIED in case of an authorization failure.
- error_details gives details about the error. May be NULL.
Definition at line 585 of file grpc_security.h.
◆ grpc_ssl_roots_override_callback
| typedef grpc_ssl_roots_override_result(* grpc_ssl_roots_override_callback) (char **pem_root_certs) |
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 containing the list of PEM encoded root certificates. The ownership is passed to the core and freed (laster by the core) with gpr_free. If this function fails and GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, it will override the roots specified this func
Definition at line 161 of file grpc_security.h.
◆ grpc_ssl_server_certificate_config
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 grpc_ssl_server_certificate_config_create().
Definition at line 474 of file grpc_security.h.
◆ grpc_ssl_server_certificate_config_callback
| typedef grpc_ssl_certificate_config_reload_status( * grpc_ssl_server_certificate_config_callback) (void *user_data, grpc_ssl_server_certificate_config **config) |
Callback to retrieve updated SSL server certificates, private keys, and trusted CAs (for client authentication).
- user_data parameter, if not NULL, contains opaque data to be used by the callback.
- Use grpc_ssl_server_certificate_config_create to create the config.
- The caller assumes ownership of the config.
Definition at line 504 of file grpc_security.h.
◆ grpc_ssl_server_credentials_options
Definition at line 533 of file grpc_security.h.
◆ grpc_ssl_session_cache
| typedef struct grpc_ssl_session_cache grpc_ssl_session_cache |
— SSL Session Cache. —
A SSL session cache object represents a way to cache client sessions between connections. Only ticket-based resumption is supported.
Definition at line 108 of file grpc_security.h.
◆ grpc_tls_certificate_provider
| typedef struct grpc_tls_certificate_provider grpc_tls_certificate_provider |
EXPERIMENTAL API - Subject to change
A struct provides ways to gain credential data that will be used in the TLS handshake.
Definition at line 720 of file grpc_security.h.
◆ grpc_tls_certificate_verifier
| typedef struct grpc_tls_certificate_verifier grpc_tls_certificate_verifier |
EXPERIMENTAL API - Subject to change
The internal verifier type that will be used inside core.
Definition at line 955 of file grpc_security.h.
◆ grpc_tls_certificate_verifier_external
EXPERIMENTAL API - 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.
◆ grpc_tls_credentials_options
| typedef struct grpc_tls_credentials_options grpc_tls_credentials_options |
— TLS channel/server credentials — It is used for experimental purpose for now and subject to change. EXPERIMENTAL API - Subject to change
A struct that can be specified by callers to configure underlying TLS behaviors.
Definition at line 712 of file grpc_security.h.
◆ grpc_tls_custom_verification_check_request
◆ grpc_tls_identity_pairs
| typedef struct grpc_tls_identity_pairs grpc_tls_identity_pairs |
EXPERIMENTAL API - Subject to change
A struct that stores the credential data presented to the peer in handshake to show local identity.
Definition at line 728 of file grpc_security.h.
◆ grpc_tls_on_custom_verification_check_done_cb
| 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
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.
Definition at line 946 of file grpc_security.h.
Function Documentation
◆ grpc_access_token_credentials_create()
| GRPCAPI grpc_call_credentials* grpc_access_token_credentials_create | ( | const char * | access_token, |
| void * | reserved | ||
| ) |
Creates an Oauth2 Access Token credentials with an access token that was acquired by an out of band mechanism.
Definition at line 744 of file oauth2_credentials.cc.
◆ grpc_alts_credentials_client_options_add_target_service_account()
| GRPCAPI void grpc_alts_credentials_client_options_add_target_service_account | ( | grpc_alts_credentials_options * | options, |
| const char * | service_account | ||
| ) |
This method adds a target service account to grpc client's ALTS credentials options instance. It is used for experimental purpose for now and subject to change.
- options: grpc ALTS credentials options instance.
- service_account: service account of target endpoint.
Definition at line 45 of file grpc_alts_credentials_client_options.cc.
◆ grpc_alts_credentials_client_options_create()
| GRPCAPI grpc_alts_credentials_options* grpc_alts_credentials_client_options_create | ( | void | ) |
This method creates a grpc ALTS credentials client options instance. It is used for experimental purpose for now and subject to change.
Definition at line 73 of file grpc_alts_credentials_client_options.cc.
◆ grpc_alts_credentials_create()
| GRPCAPI grpc_channel_credentials* grpc_alts_credentials_create | ( | const grpc_alts_credentials_options * | options | ) |
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.
It returns the created ALTS channel credential object.
Definition at line 110 of file alts_credentials.cc.
◆ grpc_alts_credentials_options_destroy()
| GRPCAPI void grpc_alts_credentials_options_destroy | ( | grpc_alts_credentials_options * | options | ) |
This method destroys a grpc_alts_credentials_options instance by de-allocating all of its occupied memory. It is used for experimental purpose for now and subject to change.
- options: a grpc_alts_credentials_options instance that needs to be destroyed.
Definition at line 38 of file grpc_alts_credentials_options.cc.
◆ grpc_alts_credentials_server_options_create()
| GRPCAPI grpc_alts_credentials_options* grpc_alts_credentials_server_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.
Definition at line 36 of file grpc_alts_credentials_server_options.cc.
◆ grpc_alts_server_credentials_create()
| GRPCAPI grpc_server_credentials* grpc_alts_server_credentials_create | ( | const grpc_alts_credentials_options * | options | ) |
This method creates an ALTS server credential object. It is used for experimental purpose for now and subject to change.
- options: grpc ALTS credentials options instance for server.
It returns the created ALTS server credential object.
Definition at line 116 of file alts_credentials.cc.
◆ grpc_auth_context_add_cstring_property()
| GRPCAPI void grpc_auth_context_add_cstring_property | ( | grpc_auth_context * | ctx, |
| const char * | name, | ||
| const char * | value | ||
| ) |
Add a C string property.
Definition at line 268 of file security_context.cc.
◆ grpc_auth_context_add_property()
| GRPCAPI void grpc_auth_context_add_property | ( | grpc_auth_context * | ctx, |
| const char * | name, | ||
| const char * | value, | ||
| size_t | value_length | ||
| ) |
– The following auth context methods should only be called by a server metadata
processor to set properties extracted from auth metadata.
Add a property.
Definition at line 248 of file security_context.cc.
◆ grpc_auth_context_find_properties_by_name()
| GRPCAPI grpc_auth_property_iterator grpc_auth_context_find_properties_by_name | ( | const grpc_auth_context * | ctx, |
| const char * | name | ||
| ) |
Finds a property in the context. May return an empty iterator (first _next will return NULL) if no property with this name was found in the context.
Definition at line 207 of file security_context.cc.
◆ grpc_auth_context_peer_identity()
| GRPCAPI grpc_auth_property_iterator grpc_auth_context_peer_identity | ( | const grpc_auth_context * | ctx | ) |
Gets the peer identity. Returns an empty iterator (first _next will return NULL) if the peer is not authenticated.
Definition at line 218 of file security_context.cc.
◆ grpc_auth_context_peer_identity_property_name()
| const GRPCAPI char* grpc_auth_context_peer_identity_property_name | ( | const grpc_auth_context * | ctx | ) |
Gets the name of the property that indicates the peer identity. Will return NULL if the peer is not authenticated.
Definition at line 144 of file security_context.cc.
◆ grpc_auth_context_peer_is_authenticated()
| GRPCAPI int grpc_auth_context_peer_is_authenticated | ( | const grpc_auth_context * | ctx | ) |
Returns 1 if the peer is authenticated, 0 otherwise.
Definition at line 168 of file security_context.cc.
◆ grpc_auth_context_property_iterator()
| GRPCAPI grpc_auth_property_iterator grpc_auth_context_property_iterator | ( | const grpc_auth_context * | ctx | ) |
Iterates over the auth context.
Definition at line 173 of file security_context.cc.
◆ grpc_auth_context_release()
| GRPCAPI void grpc_auth_context_release | ( | grpc_auth_context * | context | ) |
Releases the auth context returned from grpc_call_auth_context.
Definition at line 94 of file security_context.cc.
◆ grpc_auth_context_set_peer_identity_property_name()
| GRPCAPI int grpc_auth_context_set_peer_identity_property_name | ( | grpc_auth_context * | ctx, |
| const char * | name | ||
| ) |
Sets the property name. Returns 1 if successful or 0 in case of failure (which means that no property with this name exists).
Definition at line 151 of file security_context.cc.
◆ grpc_auth_metadata_context_copy()
| GRPCAPI void grpc_auth_metadata_context_copy | ( | grpc_auth_metadata_context * | from, |
| grpc_auth_metadata_context * | to | ||
| ) |
Performs a deep copy from from to to.
Definition at line 58 of file client_auth_filter.cc.
◆ grpc_auth_metadata_context_reset()
| GRPCAPI void grpc_auth_metadata_context_reset | ( | grpc_auth_metadata_context * | context | ) |
Releases internal resources held by context.
Definition at line 71 of file client_auth_filter.cc.
◆ grpc_auth_property_iterator_next()
| const GRPCAPI grpc_auth_property* grpc_auth_property_iterator_next | ( | grpc_auth_property_iterator * | it | ) |
Returns NULL when the iterator is at the end.
Definition at line 182 of file security_context.cc.
◆ grpc_authorization_policy_provider_file_watcher_create()
| 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. 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.
Definition at line 207 of file grpc_authorization_policy_provider.cc.
◆ grpc_authorization_policy_provider_release()
| GRPCAPI void grpc_authorization_policy_provider_release | ( | grpc_authorization_policy_provider * | provider | ) |
EXPERIMENTAL - Subject to change. Releases grpc_authorization_policy_provider object. The creator of grpc_authorization_policy_provider is responsible for its release.
Definition at line 222 of file grpc_authorization_policy_provider.cc.
◆ grpc_authorization_policy_provider_static_data_create()
| 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 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.
Definition at line 191 of file grpc_authorization_policy_provider.cc.
◆ grpc_call_auth_context()
| GRPCAPI grpc_auth_context* grpc_call_auth_context | ( | grpc_call * | call | ) |
Gets the auth context from the call. Caller needs to call grpc_auth_context_release on the returned context.
Definition at line 69 of file security_context.cc.
◆ grpc_call_credentials_release()
| GRPCAPI void grpc_call_credentials_release | ( | grpc_call_credentials * | creds | ) |
Releases a call credentials object. The creator of the credentials object is responsible for its release.
Definition at line 42 of file credentials.cc.
◆ grpc_call_set_credentials()
| GRPCAPI grpc_call_error grpc_call_set_credentials | ( | grpc_call * | call, |
| grpc_call_credentials * | creds | ||
| ) |
— Call specific credentials. — Sets a credentials to a call. Can only be called on the client side before grpc_call_start_batch.
Definition at line 46 of file security_context.cc.
◆ grpc_composite_call_credentials_create()
| GRPCAPI grpc_call_credentials* grpc_composite_call_credentials_create | ( | grpc_call_credentials * | creds1, |
| grpc_call_credentials * | creds2, | ||
| void * | reserved | ||
| ) |
— composite credentials. Creates a composite call credentials object.
Definition at line 129 of file composite_credentials.cc.
◆ grpc_composite_channel_credentials_create()
| GRPCAPI grpc_channel_credentials* grpc_composite_channel_credentials_create | ( | grpc_channel_credentials * | channel_creds, |
| grpc_call_credentials * | call_creds, | ||
| void * | reserved | ||
| ) |
Creates a composite channel credentials object. The security level of resulting connection is determined by channel_creds.
Definition at line 164 of file composite_credentials.cc.
◆ grpc_external_account_credentials_create()
| GRPCAPI grpc_call_credentials* grpc_external_account_credentials_create | ( | const char * | json_string, |
| const char * | scopes_string | ||
| ) |
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.
Definition at line 539 of file external_account_credentials.cc.
◆ grpc_google_compute_engine_credentials_create()
| GRPCAPI grpc_call_credentials* grpc_google_compute_engine_credentials_create | ( | void * | reserved | ) |
Creates a compute engine credentials object for connecting to Google. WARNING: Do NOT use this credentials to connect to a non-google service as this could result in an oauth2 token leak.
Definition at line 421 of file oauth2_credentials.cc.
◆ grpc_google_default_credentials_create()
| GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create | ( | grpc_call_credentials * | call_credentials | ) |
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.
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.
Definition at line 429 of file google_default_credentials.cc.
◆ grpc_google_iam_credentials_create()
| GRPCAPI grpc_call_credentials* grpc_google_iam_credentials_create | ( | const char * | authorization_token, |
| const char * | authority_selector, | ||
| void * | reserved | ||
| ) |
Creates an IAM credentials object for connecting to Google.
Definition at line 70 of file iam_credentials.cc.
◆ grpc_google_refresh_token_credentials_create()
| GRPCAPI grpc_call_credentials* grpc_google_refresh_token_credentials_create | ( | const char * | json_refresh_token, |
| void * | reserved | ||
| ) |
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 this could result in an oauth2 token leak.
- json_refresh_token is the JSON string containing the refresh token itself along with a client_id and client_secret.
Definition at line 508 of file oauth2_credentials.cc.
◆ grpc_insecure_credentials_create()
| GRPCAPI grpc_channel_credentials* grpc_insecure_credentials_create | ( | ) |
EXPERIMENTAL API - Subject to change
This method creates an insecure channel credentials object.
Definition at line 64 of file core/lib/security/credentials/insecure/insecure_credentials.cc.
◆ grpc_insecure_server_credentials_create()
| GRPCAPI grpc_server_credentials* grpc_insecure_server_credentials_create | ( | ) |
EXPERIMENTAL API - Subject to change
This method creates an insecure server credentials object.
Definition at line 71 of file core/lib/security/credentials/insecure/insecure_credentials.cc.
◆ grpc_local_credentials_create()
| GRPCAPI grpc_channel_credentials* grpc_local_credentials_create | ( | grpc_local_connect_type | type | ) |
— Local channel/server credentials — 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
It returns the created local channel credential object.
Definition at line 60 of file local_credentials.cc.
◆ grpc_local_server_credentials_create()
| GRPCAPI grpc_server_credentials* grpc_local_server_credentials_create | ( | grpc_local_connect_type | type | ) |
This method creates a local server credential object. It is used for experimental purpose for now and subject to change.
- type: local connection type
It returns the created local server credential object.
Definition at line 69 of file local_credentials.cc.
◆ grpc_max_auth_token_lifetime()
| GRPCAPI gpr_timespec grpc_max_auth_token_lifetime | ( | void | ) |
Definition at line 48 of file json_token.cc.
◆ grpc_metadata_credentials_create_from_plugin()
| GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin | ( | grpc_metadata_credentials_plugin | plugin, |
| grpc_security_level | min_security_level, | ||
| void * | reserved | ||
| ) |
Creates a credentials object from a plugin with a specified minimum security level.
Definition at line 208 of file plugin_credentials.cc.
◆ grpc_server_credentials_set_auth_metadata_processor()
| GRPCAPI void grpc_server_credentials_set_auth_metadata_processor | ( | grpc_server_credentials * | creds, |
| grpc_auth_metadata_processor | processor | ||
| ) |
Definition at line 112 of file credentials.cc.
◆ grpc_service_account_jwt_access_credentials_create()
| GRPCAPI grpc_call_credentials* grpc_service_account_jwt_access_credentials_create | ( | const char * | json_key, |
| gpr_timespec | token_lifetime, | ||
| void * | reserved | ||
| ) |
Creates a JWT credentials object. May return NULL if the input is invalid.
- json_key is the JSON key string containing the client's private key.
- token_lifetime is the lifetime of each Json Web Token (JWT) created with this credentials. It should not exceed grpc_max_auth_token_lifetime or will be cropped to this value.
Definition at line 154 of file jwt_credentials.cc.
◆ grpc_set_ssl_roots_override_callback()
| GRPCAPI void grpc_set_ssl_roots_override_callback | ( | grpc_ssl_roots_override_callback | cb | ) |
Setup a callback to override the default TLS/SSL roots. This function is not thread-safe and must be called at initialization time before any ssl credentials are created to have the desired side effect. If GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, the callback will not be called.
Definition at line 71 of file ssl_utils.cc.
◆ grpc_ssl_credentials_create()
| 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 | ||
| ) |
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 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.
Definition at line 132 of file ssl_credentials.cc.
◆ grpc_ssl_credentials_create_ex()
| 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 | ||
| ) |
Definition at line 148 of file ssl_credentials.cc.
◆ grpc_ssl_server_certificate_config_create()
| GRPCAPI grpc_ssl_server_certificate_config* grpc_ssl_server_certificate_config_create | ( | const char * | pem_root_certs, |
| const grpc_ssl_pem_key_cert_pair * | pem_key_cert_pairs, | ||
| size_t | num_key_cert_pairs | ||
| ) |
Creates a grpc_ssl_server_certificate_config object.
- pem_roots_cert is the NULL-terminated string containing the PEM encoding of the client root certificates. This parameter may be NULL if the server does not want the client to be authenticated with SSL.
- pem_key_cert_pairs is an array private key / certificate chains of the server. This parameter cannot be NULL.
- num_key_cert_pairs indicates the number of items in the private_key_files and cert_chain_files parameters. It must be at least 1.
- It is the caller's responsibility to free this object via grpc_ssl_server_certificate_config_destroy().
Definition at line 241 of file ssl_credentials.cc.
◆ grpc_ssl_server_certificate_config_destroy()
| GRPCAPI void grpc_ssl_server_certificate_config_destroy | ( | grpc_ssl_server_certificate_config * | config | ) |
Destroys a grpc_ssl_server_certificate_config object.
Definition at line 266 of file ssl_credentials.cc.
◆ grpc_ssl_server_credentials_create()
| GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create | ( | const char * | pem_root_certs, |
| grpc_ssl_pem_key_cert_pair * | pem_key_cert_pairs, | ||
| size_t | num_key_cert_pairs, | ||
| int | force_client_auth, | ||
| void * | reserved | ||
| ) |
Deprecated in favor of grpc_ssl_server_credentials_create_ex. Creates an SSL server_credentials object.
- pem_roots_cert is the NULL-terminated string containing the PEM encoding of the client root certificates. This parameter may be NULL if the server does not want the client to be authenticated with SSL.
- pem_key_cert_pairs is an array private key / certificate chains of the server. This parameter cannot be NULL.
- num_key_cert_pairs indicates the number of items in the private_key_files and cert_chain_files parameters. It should be at least 1.
- force_client_auth, if set to non-zero will force the client to authenticate with an SSL cert. Note that this option is ignored if pem_root_certs is NULL.
Definition at line 319 of file ssl_credentials.cc.
◆ grpc_ssl_server_credentials_create_ex()
| 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, | ||
| grpc_ssl_client_certificate_request_type | client_certificate_request, | ||
| void * | reserved | ||
| ) |
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 certificates.
Definition at line 330 of file ssl_credentials.cc.
◆ grpc_ssl_server_credentials_create_options_using_config()
| GRPCAPI grpc_ssl_server_credentials_options* grpc_ssl_server_credentials_create_options_using_config | ( | grpc_ssl_client_certificate_request_type | client_certificate_request, |
| grpc_ssl_server_certificate_config * | certificate_config | ||
| ) |
Creates an options object using a certificate config. Use this method when the certificates and keys of the SSL server will not change during the server's lifetime.
- Takes ownership of the certificate_config parameter.
Definition at line 279 of file ssl_credentials.cc.
◆ grpc_ssl_server_credentials_create_options_using_config_fetcher()
| GRPCAPI grpc_ssl_server_credentials_options* grpc_ssl_server_credentials_create_options_using_config_fetcher | ( | grpc_ssl_client_certificate_request_type | client_certificate_request, |
| grpc_ssl_server_certificate_config_callback | cb, | ||
| void * | user_data | ||
| ) |
Creates an options object using a certificate config fetcher. Use this method to reload the certificates and keys of the SSL server without interrupting the operation of the server. Initial certificate config will be fetched during server initialization.
- user_data parameter, if not NULL, contains opaque data which will be passed to the fetcher (see definition of grpc_ssl_server_certificate_config_callback).
Definition at line 296 of file ssl_credentials.cc.
◆ grpc_ssl_server_credentials_create_with_options()
| GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create_with_options | ( | grpc_ssl_server_credentials_options * | options | ) |
Creates an SSL server_credentials object using the provided options struct.
- Takes ownership of the options parameter.
Definition at line 354 of file ssl_credentials.cc.
◆ grpc_ssl_server_credentials_options_destroy()
| GRPCAPI void grpc_ssl_server_credentials_options_destroy | ( | grpc_ssl_server_credentials_options * | options | ) |
Destroys a grpc_ssl_server_credentials_options object.
Definition at line 383 of file ssl_credentials.cc.
◆ grpc_ssl_session_cache_create_channel_arg()
| GRPCAPI grpc_arg grpc_ssl_session_cache_create_channel_arg | ( | grpc_ssl_session_cache * | cache | ) |
Create a channel arg with the given cache object.
Definition at line 545 of file ssl_utils.cc.
◆ grpc_ssl_session_cache_create_lru()
| GRPCAPI grpc_ssl_session_cache* grpc_ssl_session_cache_create_lru | ( | size_t | capacity | ) |
Create LRU cache for client-side SSL sessions with the given capacity. If capacity is < 1, a default capacity is used instead.
Definition at line 516 of file ssl_utils.cc.
◆ grpc_ssl_session_cache_destroy()
| GRPCAPI void grpc_ssl_session_cache_destroy | ( | grpc_ssl_session_cache * | cache | ) |
Destroy SSL session cache.
Definition at line 521 of file ssl_utils.cc.
◆ grpc_sts_credentials_create()
| GRPCAPI grpc_call_credentials* grpc_sts_credentials_create | ( | const grpc_sts_credentials_options * | options, |
| void * | reserved | ||
| ) |
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.
Definition at line 701 of file oauth2_credentials.cc.
◆ grpc_tls_certificate_provider_file_watcher_create()
| 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 | ||
| ) |
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.
Definition at line 467 of file grpc_tls_certificate_provider.cc.
◆ grpc_tls_certificate_provider_release()
| GRPCAPI void grpc_tls_certificate_provider_release | ( | grpc_tls_certificate_provider * | provider | ) |
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.
Definition at line 477 of file grpc_tls_certificate_provider.cc.
◆ grpc_tls_certificate_provider_static_data_create()
| 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 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.
– Wrapper APIs declared in grpc_security.h –
Definition at line 449 of file grpc_tls_certificate_provider.cc.
◆ grpc_tls_certificate_verifier_cancel()
| void grpc_tls_certificate_verifier_cancel | ( | grpc_tls_certificate_verifier * | verifier, |
| grpc_tls_custom_verification_check_request * | request | ||
| ) |
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.
Definition at line 211 of file grpc_tls_certificate_verifier.cc.
◆ grpc_tls_certificate_verifier_external_create()
| grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_external_create | ( | grpc_tls_certificate_verifier_external * | external_verifier | ) |
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.
Definition at line 218 of file grpc_tls_certificate_verifier.cc.
◆ grpc_tls_certificate_verifier_host_name_create()
| grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_host_name_create | ( | ) |
EXPERIMENTAL API - Subject to change
Factory function for an internal verifier that will do the default hostname check.
Definition at line 230 of file grpc_tls_certificate_verifier.cc.
◆ grpc_tls_certificate_verifier_no_op_create()
| grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_no_op_create | ( | ) |
EXPERIMENTAL API - Subject to change
Factory function for an internal verifier that won't perform any post-handshake verification. Note: using this solely without any other authentication mechanisms on the peer identity will leave your applications to the MITM(Man-In-The-Middle) attacks. Users should avoid doing so in production environments.
Definition at line 224 of file grpc_tls_certificate_verifier.cc.
◆ grpc_tls_certificate_verifier_release()
| void grpc_tls_certificate_verifier_release | ( | grpc_tls_certificate_verifier * | verifier | ) |
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.
Definition at line 235 of file grpc_tls_certificate_verifier.cc.
◆ grpc_tls_certificate_verifier_verify()
| 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 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|.
Definition at line 187 of file grpc_tls_certificate_verifier.cc.
◆ grpc_tls_credentials_create()
| grpc_channel_credentials* grpc_tls_credentials_create | ( | grpc_tls_credentials_options * | options | ) |
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.
– Wrapper APIs declared in grpc_security.h –
Definition at line 146 of file tls_credentials.cc.
◆ grpc_tls_credentials_options_create()
| GRPCAPI grpc_tls_credentials_options* grpc_tls_credentials_options_create | ( | ) |
EXPERIMENTAL API - Subject to change
Creates an grpc_tls_credentials_options.
– Wrapper APIs declared in grpc_security.h –
Definition at line 33 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_set_cert_request_type()
| GRPCAPI void grpc_tls_credentials_options_set_cert_request_type | ( | grpc_tls_credentials_options * | options, |
| grpc_ssl_client_certificate_request_type | type | ||
| ) |
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.
Definition at line 38 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_set_certificate_provider()
| GRPCAPI void grpc_tls_credentials_options_set_certificate_provider | ( | grpc_tls_credentials_options * | options, |
| grpc_tls_certificate_provider * | provider | ||
| ) |
EXPERIMENTAL API - Subject to change
Sets the credential provider in the options. The |options| will implicitly take a new ref to the |provider|.
Definition at line 51 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_set_certificate_verifier()
| void grpc_tls_credentials_options_set_certificate_verifier | ( | grpc_tls_credentials_options * | options, |
| grpc_tls_certificate_verifier * | verifier | ||
| ) |
EXPERIMENTAL API - Subject to change
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.
Definition at line 85 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_set_check_call_host()
| GRPCAPI void grpc_tls_credentials_options_set_check_call_host | ( | grpc_tls_credentials_options * | options, |
| int | check_call_host | ||
| ) |
EXPERIMENTAL API - Subject to change
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.
Definition at line 99 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_set_crl_directory()
| GRPCAPI void grpc_tls_credentials_options_set_crl_directory | ( | grpc_tls_credentials_options * | options, |
| const char * | crl_directory | ||
| ) |
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.
Definition at line 93 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_set_identity_cert_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 name of the identity certificates being watched. If not set, We will use a default empty string as the identity certificate name.
Definition at line 79 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_set_root_cert_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
Sets the name of the root certificates being watched. If not set, We will use a default empty string as the root certificate name.
Definition at line 67 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_set_tls_session_key_log_file_path()
| GRPCAPI void grpc_tls_credentials_options_set_tls_session_key_log_file_path | ( | grpc_tls_credentials_options * | options, |
| const char * | path | ||
| ) |
— 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.
Definition at line 105 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_set_verify_server_cert()
| GRPCAPI void grpc_tls_credentials_options_set_verify_server_cert | ( | grpc_tls_credentials_options * | options, |
| int | verify_server_cert | ||
| ) |
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.
Definition at line 45 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_watch_identity_key_cert_pairs()
| GRPCAPI void grpc_tls_credentials_options_watch_identity_key_cert_pairs | ( | grpc_tls_credentials_options * | options | ) |
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.
Definition at line 73 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_credentials_options_watch_root_certs()
| GRPCAPI void grpc_tls_credentials_options_watch_root_certs | ( | grpc_tls_credentials_options * | options | ) |
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.
Definition at line 61 of file grpc_tls_credentials_options.cc.
◆ grpc_tls_identity_pairs_add_pair()
| 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
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|.
Definition at line 336 of file grpc_tls_certificate_distributor.cc.
◆ grpc_tls_identity_pairs_create()
| GRPCAPI grpc_tls_identity_pairs* grpc_tls_identity_pairs_create | ( | ) |
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.
– Wrapper APIs declared in grpc_security.h –
Definition at line 332 of file grpc_tls_certificate_distributor.cc.
◆ grpc_tls_identity_pairs_destroy()
| GRPCAPI void grpc_tls_identity_pairs_destroy | ( | grpc_tls_identity_pairs * | pairs | ) |
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.
Definition at line 345 of file grpc_tls_certificate_distributor.cc.
◆ grpc_tls_server_credentials_create()
| grpc_server_credentials* grpc_tls_server_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|.
Definition at line 155 of file tls_credentials.cc.
◆ grpc_xds_credentials_create()
| GRPCAPI grpc_channel_credentials* grpc_xds_credentials_create | ( | grpc_channel_credentials * | fallback_credentials | ) |
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.
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 fallback_credentials. (Internally takes a ref to the object.)
Definition at line 243 of file core/lib/security/credentials/xds/xds_credentials.cc.
◆ grpc_xds_server_credentials_create()
| GRPCAPI grpc_server_credentials* grpc_xds_server_credentials_create | ( | grpc_server_credentials * | fallback_credentials | ) |
EXPERIMENTAL API - Subject to change
This method creates an xDS server credentials object.
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 fallback_credentials. (Internally takes a ref to the object.)
Definition at line 249 of file core/lib/security/credentials/xds/xds_credentials.cc.