diff --git a/include/grpc/grpc_security.h b/include/grpc/grpc_security.h index 7a442e2ace2..98d6bbf257b 100644 --- a/include/grpc/grpc_security.h +++ b/include/grpc/grpc_security.h @@ -41,15 +41,16 @@ extern "C" { #endif -/* --- grpc_credentials object. --- +/* --- grpc_channel_credentials object. --- - A credentials object represents a way to authenticate a client. */ + A channel credentials object represents a way to authenticate a client on a + channel. */ -typedef struct grpc_credentials grpc_credentials; +typedef struct grpc_channel_credentials grpc_channel_credentials; -/* Releases a credentials object. +/* Releases a channel credentials object. The creator of the credentials object is responsible for its release. */ -void grpc_credentials_release(grpc_credentials *creds); +void grpc_credentials_release(grpc_channel_credentials *creds); /* Environment variable that points to the google default application credentials json key or refresh token. Used in the @@ -59,7 +60,7 @@ void grpc_credentials_release(grpc_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. */ -grpc_credentials *grpc_google_default_credentials_create(void); +grpc_channel_credentials *grpc_google_default_credentials_create(void); /* Environment variable that points to the default SSL roots file. This file must be a PEM encoded file with all the roots such as the one that can be @@ -88,19 +89,33 @@ typedef struct { - 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. */ -grpc_credentials *grpc_ssl_credentials_create( +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 a composite credentials object. */ -grpc_credentials *grpc_composite_credentials_create(grpc_credentials *creds1, - grpc_credentials *creds2, - 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; + +/* Creates a composite channel credentials object. */ +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. */ +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. WARNING: Do NOT use this credentials to connect to a non-google service as this could result in an oauth2 token leak. */ -grpc_credentials *grpc_google_compute_engine_credentials_create(void *reserved); +grpc_call_credentials *grpc_google_compute_engine_credentials_create( + void *reserved); extern const gpr_timespec grpc_max_auth_token_lifetime; @@ -109,7 +124,7 @@ extern const gpr_timespec grpc_max_auth_token_lifetime; - 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. */ -grpc_credentials *grpc_service_account_jwt_access_credentials_create( +grpc_call_credentials *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. @@ -118,16 +133,16 @@ grpc_credentials *grpc_service_account_jwt_access_credentials_create( 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. */ -grpc_credentials *grpc_google_refresh_token_credentials_create( +grpc_call_credentials *grpc_google_refresh_token_credentials_create( const char *json_refresh_token, void *reserved); /* Creates an Oauth2 Access Token credentials with an access token that was aquired by an out of band mechanism. */ -grpc_credentials *grpc_access_token_credentials_create(const char *access_token, - void *reserved); +grpc_call_credentials *grpc_access_token_credentials_create( + const char *access_token, void *reserved); /* Creates an IAM credentials object for connecting to Google. */ -grpc_credentials *grpc_google_iam_credentials_create( +grpc_call_credentials *grpc_google_iam_credentials_create( const char *authorization_token, const char *authority_selector, void *reserved); @@ -168,13 +183,13 @@ typedef struct { } grpc_metadata_credentials_plugin; /* Creates a credentials object from a plugin. */ -grpc_credentials *grpc_metadata_credentials_create_from_plugin( +grpc_call_credentials *grpc_metadata_credentials_create_from_plugin( grpc_metadata_credentials_plugin plugin, void *reserved); /* --- Secure channel creation. --- */ /* Creates a secure channel using the passed-in credentials. */ -grpc_channel *grpc_secure_channel_create(grpc_credentials *creds, +grpc_channel *grpc_secure_channel_create(grpc_channel_credentials *creds, const char *target, const grpc_channel_args *args, void *reserved); @@ -218,7 +233,7 @@ int grpc_server_add_secure_http2_port(grpc_server *server, const char *addr, /* Sets a credentials to a call. Can only be called on the client side before grpc_call_start_batch. */ grpc_call_error grpc_call_set_credentials(grpc_call *call, - grpc_credentials *creds); + grpc_call_credentials *creds); /* --- Authentication Context. --- */ diff --git a/src/core/security/credentials.h b/src/core/security/credentials.h index b213e052d34..1bf628a9466 100644 --- a/src/core/security/credentials.h +++ b/src/core/security/credentials.h @@ -54,13 +54,15 @@ typedef enum { #define GRPC_FAKE_TRANSPORT_SECURITY_TYPE "fake" -#define GRPC_CREDENTIALS_TYPE_SSL "Ssl" -#define GRPC_CREDENTIALS_TYPE_OAUTH2 "Oauth2" -#define GRPC_CREDENTIALS_TYPE_METADATA_PLUGIN "Plugin" -#define GRPC_CREDENTIALS_TYPE_JWT "Jwt" -#define GRPC_CREDENTIALS_TYPE_IAM "Iam" -#define GRPC_CREDENTIALS_TYPE_COMPOSITE "Composite" -#define GRPC_CREDENTIALS_TYPE_FAKE_TRANSPORT_SECURITY "FakeTransportSecurity" +#define GRPC_CHANNEL_CREDENTIALS_TYPE_SSL "Ssl" +#define GRPC_CHANNEL_CREDENTIALS_TYPE_FAKE_TRANSPORT_SECURITY \ + "FakeTransportSecurity" + +#define GRPC_CALL_CREDENTIALS_TYPE_OAUTH2 "Oauth2" +#define GRPC_CALL_CREDENTIALS_TYPE_METADATA_PLUGIN "Plugin" +#define GRPC_CALL_CREDENTIALS_TYPE_JWT "Jwt" +#define GRPC_CALL_CREDENTIALS_TYPE_IAM "Iam" +#define GRPC_CALL_CREDENTIALS_TYPE_COMPOSITE "Composite" #define GRPC_AUTHORIZATION_METADATA_KEY "Authorization" #define GRPC_IAM_AUTHORIZATION_TOKEN_METADATA_KEY \ @@ -87,6 +89,41 @@ typedef enum { #define GRPC_REFRESH_TOKEN_POST_BODY_FORMAT_STRING \ "client_id=%s&client_secret=%s&refresh_token=%s&grant_type=refresh_token" +/* --- Google utils --- */ + +/* It is the caller's responsibility to gpr_free the result if not NULL. */ +char *grpc_get_well_known_google_credentials_file_path(void); + +/* --- grpc_channel_credentials. --- */ + +typedef struct { + void (*destruct)(grpc_channel_credentials *c); + grpc_security_status (*create_security_connector)( + grpc_channel_credentials *c, const char *target, const grpc_channel_args *args, + grpc_call_credentials *call_creds, + grpc_channel_security_connector **sc, grpc_channel_args **new_args); +} grpc_channel_credentials_vtable; + +struct grpc_channel_credentials { + const grpc_channel_credentials_vtable *vtable; + const char *type; + gpr_refcount refcount; + grpc_call_credentials *call_creds; +}; + +grpc_channel_credentials *grpc_channel_credentials_ref( + grpc_channel_credentials *creds); +void grpc_channel_credentials_unref(grpc_channel_credentials *creds); + +/* Creates a security connector for the channel. May also create new channel + args for the channel to be used in place of the passed in const args if + returned non NULL. In that case the caller is responsible for destroying + new_args after channel creation. */ +grpc_security_status grpc_channel_credentials_create_security_connector( + grpc_channel_credentials *creds, const char *target, + const grpc_channel_args *args, grpc_call_credentials *call_creds, + grpc_channel_security_connector **sc, grpc_channel_args **new_args); + /* --- grpc_credentials_md. --- */ typedef struct { @@ -113,16 +150,7 @@ grpc_credentials_md_store *grpc_credentials_md_store_ref( grpc_credentials_md_store *store); void grpc_credentials_md_store_unref(grpc_credentials_md_store *store); -/* --- grpc_credentials. --- */ - -/* Creates a fake transport security credentials object for testing. */ -grpc_credentials *grpc_fake_transport_security_credentials_create(void); -/* Creates a fake server transport security credentials object for testing. */ -grpc_server_credentials *grpc_fake_transport_security_server_credentials_create( - void); - -/* It is the caller's responsibility to gpr_free the result if not NULL. */ -char *grpc_get_well_known_google_credentials_file_path(void); +/* --- grpc_call_credentials. --- */ typedef void (*grpc_credentials_metadata_cb)(grpc_exec_ctx *exec_ctx, void *user_data, @@ -131,57 +159,47 @@ typedef void (*grpc_credentials_metadata_cb)(grpc_exec_ctx *exec_ctx, grpc_credentials_status status); typedef struct { - void (*destruct)(grpc_credentials *c); - int (*has_request_metadata)(const grpc_credentials *c); - int (*has_request_metadata_only)(const grpc_credentials *c); - void (*get_request_metadata)(grpc_exec_ctx *exec_ctx, grpc_credentials *c, - grpc_pollset *pollset, const char *service_url, + void (*destruct)(grpc_call_credentials *c); + int (*has_request_metadata)(const grpc_call_credentials *c); + void (*get_request_metadata)(grpc_exec_ctx *exec_ctx, + grpc_call_credentials *c, grpc_pollset *pollset, + const char *service_url, grpc_credentials_metadata_cb cb, void *user_data); - grpc_security_status (*create_security_connector)( - grpc_credentials *c, const char *target, const grpc_channel_args *args, - grpc_credentials *request_metadata_creds, - grpc_channel_security_connector **sc, grpc_channel_args **new_args); -} grpc_credentials_vtable; +} grpc_call_credentials_vtable; -struct grpc_credentials { - const grpc_credentials_vtable *vtable; +struct grpc_call_credentials { + const grpc_call_credentials_vtable *vtable; const char *type; gpr_refcount refcount; }; -grpc_credentials *grpc_credentials_ref(grpc_credentials *creds); -void grpc_credentials_unref(grpc_credentials *creds); -int grpc_credentials_has_request_metadata(grpc_credentials *creds); -int grpc_credentials_has_request_metadata_only(grpc_credentials *creds); -void grpc_credentials_get_request_metadata( - grpc_exec_ctx *exec_ctx, grpc_credentials *creds, grpc_pollset *pollset, - const char *service_url, grpc_credentials_metadata_cb cb, void *user_data); +grpc_call_credentials *grpc_credentials_ref(grpc_call_credentials *creds); +void grpc_call_credentials_unref(grpc_call_credentials *creds); +int grpc_call_credentials_has_request_metadata(grpc_call_credentials *creds); +void grpc_call_credentials_get_request_metadata(grpc_exec_ctx *exec_ctx, + grpc_call_credentials *creds, + grpc_pollset *pollset, + const char *service_url, + grpc_credentials_metadata_cb cb, + void *user_data); -/* Creates a security connector for the channel. May also create new channel - args for the channel to be used in place of the passed in const args if - returned non NULL. In that case the caller is responsible for destroying - new_args after channel creation. */ -grpc_security_status grpc_credentials_create_security_connector( - grpc_credentials *creds, const char *target, const grpc_channel_args *args, - grpc_credentials *request_metadata_creds, - grpc_channel_security_connector **sc, grpc_channel_args **new_args); typedef struct { - grpc_credentials **creds_array; + grpc_call_credentials **creds_array; size_t num_creds; -} grpc_credentials_array; +} grpc_call_credentials_array; -const grpc_credentials_array *grpc_composite_credentials_get_credentials( - grpc_credentials *composite_creds); +const grpc_call_credentials_array *grpc_composite_credentials_get_credentials( + grpc_call_credentials *composite_creds); /* Returns creds if creds is of the specified type or the inner creds of the specified type (if found), if the creds is of type COMPOSITE. If composite_creds is not NULL, *composite_creds will point to creds if of type COMPOSITE in case of success. */ -grpc_credentials *grpc_credentials_contains_type( - grpc_credentials *creds, const char *type, - grpc_credentials **composite_creds); +grpc_call_credentials *grpc_credentials_contains_type( + grpc_call_credentials *creds, const char *type, + grpc_call_credentials **composite_creds); /* Exposed for testing only. */ grpc_credentials_status @@ -192,19 +210,19 @@ void grpc_flush_cached_google_default_credentials(void); /* Metadata-only credentials with the specified key and value where asynchronicity can be simulated for testing. */ -grpc_credentials *grpc_md_only_test_credentials_create(const char *md_key, - const char *md_value, - int is_async); +grpc_call_credentials *grpc_md_only_test_credentials_create( + const char *md_key, const char *md_value, int is_async); /* Private constructor for jwt credentials from an already parsed json key. Takes ownership of the key. */ -grpc_credentials * +grpc_call_credentials * grpc_service_account_jwt_access_credentials_create_from_auth_json_key( grpc_auth_json_key key, gpr_timespec token_lifetime); /* Private constructor for refresh token credentials from an already parsed refresh token. Takes ownership of the refresh token. */ -grpc_credentials *grpc_refresh_token_credentials_create_from_auth_refresh_token( +grpc_call_credentials * +grpc_refresh_token_credentials_create_from_auth_refresh_token( grpc_auth_refresh_token token); /* --- grpc_server_credentials. --- */ @@ -231,10 +249,18 @@ grpc_server_credentials *grpc_server_credentials_ref( void grpc_server_credentials_unref(grpc_server_credentials *creds); +/* -- Fake transport security credentials. -- */ + +/* Creates a fake transport security credentials object for testing. */ +grpc_channel_credentials *grpc_fake_transport_security_credentials_create(void); +/* Creates a fake server transport security credentials object for testing. */ +grpc_server_credentials *grpc_fake_transport_security_server_credentials_create( + void); + /* -- Ssl credentials. -- */ typedef struct { - grpc_credentials base; + grpc_channel_credentials base; grpc_ssl_config config; } grpc_ssl_credentials; @@ -246,7 +272,7 @@ typedef struct { /* -- Jwt credentials -- */ typedef struct { - grpc_credentials base; + grpc_call_credentials base; /* Have a simple cache for now with just 1 entry. We could have a map based on the service_url for a more sophisticated one. */ @@ -277,7 +303,7 @@ typedef void (*grpc_fetch_oauth2_func)(grpc_exec_ctx *exec_ctx, gpr_timespec deadline); typedef struct { - grpc_credentials base; + grpc_call_credentials base; gpr_mu mu; grpc_credentials_md_store *access_token_md; gpr_timespec token_expiration; @@ -295,14 +321,14 @@ typedef struct { /* -- Oauth2 Access Token credentials. -- */ typedef struct { - grpc_credentials base; + grpc_call_credentials base; grpc_credentials_md_store *access_token_md; } grpc_access_token_credentials; /* -- Metadata-only Test credentials. -- */ typedef struct { - grpc_credentials base; + grpc_call_credentials base; grpc_credentials_md_store *md_store; int is_async; } grpc_md_only_test_credentials; @@ -310,22 +336,21 @@ typedef struct { /* -- GoogleIAM credentials. -- */ typedef struct { - grpc_credentials base; + grpc_call_credentials base; grpc_credentials_md_store *iam_md; } grpc_google_iam_credentials; /* -- Composite credentials. -- */ typedef struct { - grpc_credentials base; - grpc_credentials_array inner; - grpc_credentials *connector_creds; + grpc_call_credentials base; + grpc_call_credentials_array inner; } grpc_composite_credentials; /* -- Plugin credentials. -- */ typedef struct { - grpc_credentials base; + grpc_call_credentials base; grpc_metadata_credentials_plugin plugin; grpc_credentials_md_store *plugin_md; } grpc_plugin_credentials;