#include <grpc/grpc.h>
#include <grpc/grpc_security_constants.h>
#include <grpc/status.h>

Data Structures
struct	grpc_auth_property_iterator

struct	grpc_auth_property
	value, if not NULL, is guaranteed to be NULL terminated. More...

struct	grpc_ssl_pem_key_cert_pair
	Object that holds a private key / certificate chain pair in PEM format. More...

struct	grpc_auth_metadata_context
	Context that can be used by metadata credentials plugin in order to create auth related metadata. More...

struct	grpc_metadata_credentials_plugin
	grpc_metadata_credentials plugin is an API user provided structure used to create grpc_credentials objects that can be set on a channel (composed) or a call. More...

struct	grpc_auth_metadata_processor
	Pluggable server-side metadata processor object. More...

Typedefs
typedef struct grpc_auth_context	grpc_auth_context
	— Authentication Context. More...

typedef struct grpc_auth_property_iterator	grpc_auth_property_iterator

typedef struct grpc_auth_property	grpc_auth_property
	value, if not NULL, is guaranteed to be NULL terminated. More...

typedef struct grpc_channel_credentials	grpc_channel_credentials
	— grpc_channel_credentials object. More...

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. More...

typedef struct grpc_call_credentials	grpc_call_credentials
	— grpc_call_credentials object. More...

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. More...

typedef struct grpc_server_credentials	grpc_server_credentials
	— grpc_server_credentials object. More...

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 — More...

Functions
GRPCAPI const grpc_auth_property *	grpc_auth_property_iterator_next (grpc_auth_property_iterator *it)
	Returns NULL when the iterator is at the end. More...

GRPCAPI grpc_auth_property_iterator	grpc_auth_context_property_iterator (const grpc_auth_context *ctx)
	Iterates over the auth context. More...

GRPCAPI grpc_auth_property_iterator	grpc_auth_context_peer_identity (const grpc_auth_context *ctx)
	Gets the peer identity. More...

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. More...

GRPCAPI const char *	grpc_auth_context_peer_identity_property_name (const grpc_auth_context *ctx)
	Gets the name of the property that indicates the peer identity. More...

GRPCAPI int	grpc_auth_context_peer_is_authenticated (const grpc_auth_context *ctx)
	Returns 1 if the peer is authenticated, 0 otherwise. More...

GRPCAPI grpc_auth_context *	grpc_call_auth_context (grpc_call *call)
	Gets the auth context from the call. More...

GRPCAPI void	grpc_auth_context_release (grpc_auth_context *context)
	Releases the auth context returned from grpc_call_auth_context. More...

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. More...

GRPCAPI void	grpc_auth_context_add_cstring_property (grpc_auth_context ctx, const char name, const char *value)
	Add a C string property. More...

GRPCAPI int	grpc_auth_context_set_peer_identity_property_name (grpc_auth_context ctx, const char name)
	Sets the property name. More...

GRPCAPI void	grpc_channel_credentials_release (grpc_channel_credentials *creds)
	Releases a channel credentials object. More...

GRPCAPI grpc_channel_credentials *	grpc_google_default_credentials_create (void)
	Creates default credentials to connect to a google gRPC service. More...

GRPCAPI void	grpc_set_ssl_roots_override_callback (grpc_ssl_roots_override_callback cb)
	Setup a callback to override the default TLS/SSL roots. More...

GRPCAPI grpc_channel_credentials *	grpc_ssl_credentials_create (const char pem_root_certs, grpc_ssl_pem_key_cert_pair pem_key_cert_pair, void *reserved)
	Creates an SSL credentials object. More...

GRPCAPI void	grpc_call_credentials_release (grpc_call_credentials *creds)
	Releases a call credentials object. More...

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. More...

GRPCAPI grpc_call_credentials *	grpc_composite_call_credentials_create (grpc_call_credentials creds1, grpc_call_credentials creds2, void *reserved)
	Creates a composite call credentials object. More...

GRPCAPI grpc_call_credentials *	grpc_google_compute_engine_credentials_create (void *reserved)
	Creates a compute engine credentials object for connecting to Google. More...

GRPCAPI gpr_timespec	grpc_max_auth_token_lifetime ()

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. More...

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. More...

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 aquired by an out of band mechanism. More...

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. More...

GRPCAPI grpc_call_credentials *	grpc_metadata_credentials_create_from_plugin (grpc_metadata_credentials_plugin plugin, void *reserved)
	Creates a credentials object from a plugin. More...

GRPCAPI grpc_channel *	grpc_secure_channel_create (grpc_channel_credentials creds, const char target, const grpc_channel_args args, void reserved)
	— Secure channel creation. More...

GRPCAPI void	grpc_server_credentials_release (grpc_server_credentials *creds)
	Releases a server_credentials object. More...

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. More...

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)
	Same as grpc_ssl_server_credentials_create method except uses grpc_ssl_client_certificate_request_type enum to support more ways to authenticate client cerificates. More...

GRPCAPI int	grpc_server_add_secure_http2_port (grpc_server server, const char addr, grpc_server_credentials *creds)
	— Server-side secure ports. More...

GRPCAPI grpc_call_error	grpc_call_set_credentials (grpc_call call, grpc_call_credentials creds)
	— Call specific credentials. More...

GRPCAPI void	grpc_server_credentials_set_auth_metadata_processor (grpc_server_credentials *creds, grpc_auth_metadata_processor processor)

Typedef Documentation

typedef struct grpc_auth_context grpc_auth_context

— Authentication Context.

typedef struct grpc_auth_property grpc_auth_property

value, if not NULL, is guaranteed to be NULL terminated.

typedef struct grpc_auth_property_iterator grpc_auth_property_iterator

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.

typedef struct grpc_channel_credentials grpc_channel_credentials

— grpc_channel_credentials object.

A channel credentials object represents a way to authenticate a client on a channel.

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.

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.

typedef struct grpc_server_credentials grpc_server_credentials

— grpc_server_credentials object.

A server credentials object represents a way to authenticate a server.

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

Function Documentation

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 aquired by an out of band mechanism.

GRPCAPI void grpc_auth_context_add_cstring_property	(	grpc_auth_context *	ctx,
		const char *	name,
		const char *	value
	)

Add a C string 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.

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.

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.

GRPCAPI const 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.

GRPCAPI int grpc_auth_context_peer_is_authenticated ( const grpc_auth_context * ctx )

Returns 1 if the peer is authenticated, 0 otherwise.

GRPCAPI grpc_auth_property_iterator grpc_auth_context_property_iterator ( const grpc_auth_context * ctx )

Iterates over the auth context.

GRPCAPI void grpc_auth_context_release ( grpc_auth_context * context )

Releases the auth context returned from grpc_call_auth_context.

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).

GRPCAPI const grpc_auth_property* grpc_auth_property_iterator_next ( grpc_auth_property_iterator * it )

Returns NULL when the iterator is at the end.

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.

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.

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.

GRPCAPI void grpc_channel_credentials_release ( grpc_channel_credentials * creds )

Releases a channel credentials object.

The creator of the credentials object is responsible for its release.

GRPCAPI grpc_call_credentials* grpc_composite_call_credentials_create	(	grpc_call_credentials *	creds1,
		grpc_call_credentials *	creds2,
		void *	reserved
	)

Creates a composite call credentials object.

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.

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.

GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create ( void )

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.

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.

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.

GRPCAPI gpr_timespec grpc_max_auth_token_lifetime ( )

GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin	(	grpc_metadata_credentials_plugin	plugin,
		void *	reserved
	)

Creates a credentials object from a plugin.

GRPCAPI grpc_channel* grpc_secure_channel_create	(	grpc_channel_credentials *	creds,
		const char *	target,
		const grpc_channel_args *	args,
		void *	reserved
	)

— Secure channel creation.

Creates a secure channel using the passed-in credentials.

GRPCAPI int grpc_server_add_secure_http2_port	(	grpc_server *	server,
		const char *	addr,
		grpc_server_credentials *	creds
	)

— 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 void grpc_server_credentials_release ( grpc_server_credentials * creds )

Releases a server_credentials object.

The creator of the server_credentials object is responsible for its release.

GRPCAPI void grpc_server_credentials_set_auth_metadata_processor	(	grpc_server_credentials *	creds,
		grpc_auth_metadata_processor	processor
	)

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.

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.

GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create	(	const char *	pem_root_certs,
		grpc_ssl_pem_key_cert_pair *	pem_key_cert_pair,
		void *	reserved
	)

Creates an SSL credentials object.

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).
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.

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.

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
	)

Same as grpc_ssl_server_credentials_create method except uses grpc_ssl_client_certificate_request_type enum to support more ways to authenticate client cerificates.

Data Structures

Typedefs

Functions

Typedef Documentation

Function Documentation