diff options
author | 2017-05-03 14:49:41 -0700 | |
---|---|---|
committer | 2017-05-05 11:02:07 -0700 | |
commit | d809a15ec4913c7a8cd38d679a78b3edcb716b69 (patch) | |
tree | 32a3f1cfe4604c1c1003f25a6bbdfd95314e82aa /include/grpc/grpc_security.h | |
parent | 3f716baa0a33529592c6cfeb64950fe463c4595f (diff) |
cpp doc nits
Diffstat (limited to 'include/grpc/grpc_security.h')
-rw-r--r-- | include/grpc/grpc_security.h | 116 |
1 files changed, 58 insertions, 58 deletions
diff --git a/include/grpc/grpc_security.h b/include/grpc/grpc_security.h index 5d3cc4fd67..4f35506882 100644 --- a/include/grpc/grpc_security.h +++ b/include/grpc/grpc_security.h @@ -42,7 +42,7 @@ extern "C" { #endif -/* --- Authentication Context. --- */ +/** --- Authentication Context. --- */ typedef struct grpc_auth_context grpc_auth_context; @@ -52,84 +52,84 @@ typedef struct grpc_auth_property_iterator { const char *name; } grpc_auth_property_iterator; -/* value, if not NULL, is guaranteed to be NULL terminated. */ +/** value, if not NULL, is guaranteed to be NULL terminated. */ typedef struct grpc_auth_property { char *name; char *value; size_t value_length; } grpc_auth_property; -/* Returns NULL when the iterator is at the end. */ +/** Returns NULL when the iterator is at the end. */ GRPCAPI const grpc_auth_property *grpc_auth_property_iterator_next( grpc_auth_property_iterator *it); -/* Iterates over the auth context. */ +/** Iterates over the auth context. */ GRPCAPI grpc_auth_property_iterator grpc_auth_context_property_iterator(const grpc_auth_context *ctx); -/* Gets the peer identity. Returns an empty iterator (first _next will return +/** Gets the peer identity. Returns an empty iterator (first _next will return NULL) if the peer is not authenticated. */ GRPCAPI grpc_auth_property_iterator grpc_auth_context_peer_identity(const grpc_auth_context *ctx); -/* Finds a property in the context. May return an empty iterator (first _next +/** 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_find_properties_by_name( const grpc_auth_context *ctx, const char *name); -/* Gets the name of the property that indicates the peer identity. Will return +/** Gets the name of the property that indicates the peer identity. Will return NULL if the peer is not authenticated. */ GRPCAPI const char *grpc_auth_context_peer_identity_property_name( const grpc_auth_context *ctx); -/* Returns 1 if the peer is authenticated, 0 otherwise. */ +/** Returns 1 if the peer is authenticated, 0 otherwise. */ GRPCAPI int grpc_auth_context_peer_is_authenticated( const grpc_auth_context *ctx); -/* Gets the auth context from the call. Caller needs to call +/** Gets the auth context from the call. Caller needs to call grpc_auth_context_release on the returned context. */ GRPCAPI grpc_auth_context *grpc_call_auth_context(grpc_call *call); -/* Releases the auth context returned from grpc_call_auth_context. */ +/** Releases the auth context returned from grpc_call_auth_context. */ GRPCAPI void grpc_auth_context_release(grpc_auth_context *context); -/* -- +/** -- The following auth context methods should only be called by a server metadata processor to set properties extracted from auth metadata. -- */ -/* Add a property. */ +/** Add a property. */ GRPCAPI void grpc_auth_context_add_property(grpc_auth_context *ctx, const char *name, const char *value, size_t value_length); -/* Add a C string property. */ +/** Add a C string property. */ GRPCAPI void grpc_auth_context_add_cstring_property(grpc_auth_context *ctx, const char *name, const char *value); -/* Sets the property name. Returns 1 if successful or 0 in case of failure +/** Sets the property name. Returns 1 if successful or 0 in case of failure (which means that no property with this name exists). */ GRPCAPI int grpc_auth_context_set_peer_identity_property_name( grpc_auth_context *ctx, const char *name); -/* --- grpc_channel_credentials object. --- +/** --- grpc_channel_credentials object. --- A channel credentials object represents a way to authenticate a client on a channel. */ typedef struct grpc_channel_credentials grpc_channel_credentials; -/* Releases a channel credentials object. +/** Releases a channel credentials object. The creator of the credentials object is responsible for its release. */ GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials *creds); -/* Creates default credentials to connect to a google gRPC service. +/** 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_channel_credentials *grpc_google_default_credentials_create(void); -/* Callback for getting the SSL roots override from the application. +/** 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. @@ -138,7 +138,7 @@ GRPCAPI grpc_channel_credentials *grpc_google_default_credentials_create(void); typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)( char **pem_root_certs); -/* Setup a callback to override the default TLS/SSL roots. +/** 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 @@ -146,18 +146,18 @@ typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)( GRPCAPI void grpc_set_ssl_roots_override_callback( grpc_ssl_roots_override_callback cb); -/* Object that holds a private key / certificate chain pair in PEM format. */ +/** Object that holds a private key / certificate chain pair in PEM format. */ typedef struct { - /* private_key is the NULL-terminated string containing the PEM encoding of + /** private_key is the NULL-terminated string containing the PEM encoding of the client's private key. */ const char *private_key; - /* cert_chain is the NULL-terminated string containing the PEM encoding of + /** cert_chain is the NULL-terminated string containing the PEM encoding of the client's certificate chain. */ const char *cert_chain; } grpc_ssl_pem_key_cert_pair; -/* Creates an SSL credentials object. +/** 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 @@ -172,7 +172,7 @@ 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); -/* --- grpc_call_credentials object. +/** --- 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 @@ -180,21 +180,21 @@ GRPCAPI grpc_channel_credentials *grpc_ssl_credentials_create( typedef struct grpc_call_credentials grpc_call_credentials; -/* Releases a call credentials object. +/** 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. */ +/** Creates a composite channel 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 call credentials object. */ +/** Creates a composite call credentials object. */ GRPCAPI grpc_call_credentials *grpc_composite_call_credentials_create( grpc_call_credentials *creds1, grpc_call_credentials *creds2, void *reserved); -/* Creates a compute engine credentials object for connecting to Google. +/** 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_call_credentials *grpc_google_compute_engine_credentials_create( @@ -202,7 +202,7 @@ GRPCAPI grpc_call_credentials *grpc_google_compute_engine_credentials_create( GRPCAPI gpr_timespec grpc_max_auth_token_lifetime(); -/* Creates a JWT credentials object. May return NULL if the input is invalid. +/** 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 @@ -212,7 +212,7 @@ grpc_service_account_jwt_access_credentials_create(const char *json_key, gpr_timespec token_lifetime, void *reserved); -/* Creates an Oauth2 Refresh Token credentials object for connecting to Google. +/** 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. @@ -221,17 +221,17 @@ grpc_service_account_jwt_access_credentials_create(const char *json_key, GRPCAPI grpc_call_credentials *grpc_google_refresh_token_credentials_create( const char *json_refresh_token, void *reserved); -/* Creates an Oauth2 Access Token credentials with an access token that was +/** Creates an Oauth2 Access Token credentials with an access token that was aquired by an out of band mechanism. */ GRPCAPI grpc_call_credentials *grpc_access_token_credentials_create( const char *access_token, void *reserved); -/* Creates an IAM credentials object for connecting to Google. */ +/** Creates an IAM credentials object for connecting to Google. */ GRPCAPI grpc_call_credentials *grpc_google_iam_credentials_create( const char *authorization_token, const char *authority_selector, void *reserved); -/* Callback function to be called by the metadata credentials plugin +/** 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). @@ -246,31 +246,31 @@ 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); -/* Context that can be used by metadata credentials plugin in order to create +/** Context that can be used by metadata credentials plugin in order to create auth related metadata. */ typedef struct { - /* The fully qualifed service url. */ + /** The fully qualifed service url. */ const char *service_url; - /* The method name of the RPC being called (not fully qualified). + /** The method name of the RPC being called (not fully qualified). The fully qualified method name can be built from the service_url: full_qualified_method_name = ctx->service_url + '/' + ctx->method_name. */ const char *method_name; - /* The auth_context of the channel which gives the server's identity. */ + /** The auth_context of the channel which gives the server's identity. */ const grpc_auth_context *channel_auth_context; - /* Reserved for future use. */ + /** Reserved for future use. */ void *reserved; } grpc_auth_metadata_context; -/* grpc_metadata_credentials plugin is an API user provided structure used to +/** 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. See grpc_credentials_metadata_create_from_plugin below. The grpc client stack will call the get_metadata method of the plugin for every call in scope for the credentials created from it. */ typedef struct { - /* The implementation of this method has to be non-blocking. + /** The implementation of this method has to be non-blocking. - context is the information that can be used by the plugin to create auth metadata. - cb is the callback that needs to be called when the metadata is ready. @@ -278,39 +278,39 @@ typedef struct { void (*get_metadata)(void *state, grpc_auth_metadata_context context, grpc_credentials_plugin_metadata_cb cb, void *user_data); - /* Destroys the plugin state. */ + /** Destroys the plugin state. */ void (*destroy)(void *state); - /* State that will be set as the first parameter of the methods above. */ + /** State that will be set as the first parameter of the methods above. */ void *state; - /* Type of credentials that this plugin is implementing. */ + /** Type of credentials that this plugin is implementing. */ const char *type; } grpc_metadata_credentials_plugin; -/* Creates a credentials object from a plugin. */ +/** Creates a credentials object from a plugin. */ GRPCAPI grpc_call_credentials *grpc_metadata_credentials_create_from_plugin( grpc_metadata_credentials_plugin plugin, void *reserved); -/* --- Secure channel creation. --- */ +/** --- Secure channel creation. --- */ -/* Creates a secure channel using the passed-in credentials. */ +/** Creates a secure channel using the passed-in credentials. */ 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. --- +/** --- 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. +/** 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); -/* Deprecated in favor of grpc_ssl_server_credentials_create_ex. +/** 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 @@ -326,7 +326,7 @@ 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); -/* Same as grpc_ssl_server_credentials_create method except uses +/** 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.*/ GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create_ex( @@ -335,25 +335,25 @@ GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create_ex( grpc_ssl_client_certificate_request_type client_certificate_request, void *reserved); -/* --- Server-side secure ports. --- */ +/** --- Server-side secure ports. --- */ -/* Add a HTTP2 over an encrypted link over tcp listener. +/** 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. --- */ +/** --- Call specific credentials. --- */ -/* Sets a credentials to a call. Can only be called on the client side before +/** Sets a credentials to a call. Can only be called on the client side before grpc_call_start_batch. */ GRPCAPI grpc_call_error grpc_call_set_credentials(grpc_call *call, grpc_call_credentials *creds); -/* --- Auth Metadata Processing --- */ +/** --- Auth Metadata Processing --- */ -/* Callback function that is called when the metadata processing is done. +/** 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. @@ -367,9 +367,9 @@ typedef void (*grpc_process_auth_metadata_done_cb)( const grpc_metadata *response_md, size_t num_response_md, grpc_status_code status, const char *error_details); -/* Pluggable server-side metadata processor object. */ +/** Pluggable server-side metadata processor object. */ typedef struct { - /* The context object is read/write: it contains the properties of the + /** The context object is read/write: it contains the properties of the channel peer and it is the job of the process function to augment it with properties derived from the passed-in metadata. The lifetime of these objects is guaranteed until cb is invoked. */ |