GRPC Core  9.0.0
credentials.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2015 gRPC authors.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  */
18 
19 #ifndef GRPC_CORE_LIB_SECURITY_CREDENTIALS_CREDENTIALS_H
20 #define GRPC_CORE_LIB_SECURITY_CREDENTIALS_CREDENTIALS_H
21 
23 
24 #include <grpc/grpc.h>
25 #include <grpc/grpc_security.h>
26 #include <grpc/support/sync.h>
28 
29 #include "src/core/lib/gprpp/map.h"
36 
37 struct grpc_http_response;
38 
39 /* --- Constants. --- */
40 
41 typedef enum {
45 
46 #define GRPC_FAKE_TRANSPORT_SECURITY_TYPE "fake"
47 
48 #define GRPC_CHANNEL_CREDENTIALS_TYPE_SSL "Ssl"
49 #define GRPC_CHANNEL_CREDENTIALS_TYPE_FAKE_TRANSPORT_SECURITY \
50  "FakeTransportSecurity"
51 #define GRPC_CHANNEL_CREDENTIALS_TYPE_GOOGLE_DEFAULT "GoogleDefault"
52 
53 #define GRPC_CALL_CREDENTIALS_TYPE_OAUTH2 "Oauth2"
54 #define GRPC_CALL_CREDENTIALS_TYPE_JWT "Jwt"
55 #define GRPC_CALL_CREDENTIALS_TYPE_IAM "Iam"
56 #define GRPC_CALL_CREDENTIALS_TYPE_COMPOSITE "Composite"
57 
58 #define GRPC_AUTHORIZATION_METADATA_KEY "authorization"
59 #define GRPC_IAM_AUTHORIZATION_TOKEN_METADATA_KEY \
60  "x-goog-iam-authorization-token"
61 #define GRPC_IAM_AUTHORITY_SELECTOR_METADATA_KEY "x-goog-iam-authority-selector"
62 
63 #define GRPC_SECURE_TOKEN_REFRESH_THRESHOLD_SECS 60
64 
65 #define GRPC_COMPUTE_ENGINE_METADATA_HOST "metadata.google.internal."
66 #define GRPC_COMPUTE_ENGINE_METADATA_TOKEN_PATH \
67  "/computeMetadata/v1/instance/service-accounts/default/token"
68 
69 #define GRPC_GOOGLE_OAUTH2_SERVICE_HOST "oauth2.googleapis.com"
70 #define GRPC_GOOGLE_OAUTH2_SERVICE_TOKEN_PATH "/token"
71 
72 #define GRPC_SERVICE_ACCOUNT_POST_BODY_PREFIX \
73  "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&" \
74  "assertion="
75 
76 #define GRPC_REFRESH_TOKEN_POST_BODY_FORMAT_STRING \
77  "client_id=%s&client_secret=%s&refresh_token=%s&grant_type=refresh_token"
78 
79 /* --- Google utils --- */
80 
81 /* It is the caller's responsibility to gpr_free the result if not NULL. */
83 
84 /* Implementation function for the different platforms. */
86 
87 /* Override for testing only. Not thread-safe */
88 typedef char* (*grpc_well_known_credentials_path_getter)(void);
91 
92 /* --- grpc_channel_credentials. --- */
93 
94 #define GRPC_ARG_CHANNEL_CREDENTIALS "grpc.channel_credentials"
95 
96 // This type is forward declared as a C struct and we cannot define it as a
97 // class. Otherwise, compiler will complain about type mismatch due to
98 // -Wmismatched-tags.
100  : grpc_core::RefCounted<grpc_channel_credentials> {
101  public:
102  explicit grpc_channel_credentials(const char* type) : type_(type) {}
103  virtual ~grpc_channel_credentials() = default;
104 
105  // Creates a security connector for the channel. May also create new channel
106  // args for the channel to be used in place of the passed in const args if
107  // returned non NULL. In that case the caller is responsible for destroying
108  // new_args after channel creation.
112  const char* target, const grpc_channel_args* args,
113  grpc_channel_args** new_args) = 0;
114 
115  // Creates a version of the channel credentials without any attached call
116  // credentials. This can be used in order to open a channel to a non-trusted
117  // gRPC load balancer.
120  // By default we just increment the refcount.
121  return Ref();
122  }
123 
124  // Allows credentials to optionally modify a parent channel's args.
125  // By default, leave channel args as is. The callee takes ownership
126  // of the passed-in channel args, and the caller takes ownership
127  // of the returned channel args.
129  return args;
130  }
131 
132  // Attaches control_plane_creds to the local registry, under authority,
133  // if no other creds are currently registered under authority. Returns
134  // true if registered successfully and false if not.
135  bool attach_credentials(
136  const char* authority,
138 
139  // Gets the control plane credentials registered under authority. This
140  // prefers the local control plane creds registry but falls back to the
141  // global registry. Lastly, this returns self but with any attached
142  // call credentials stripped off, in the case that neither the local
143  // registry nor the global registry have an entry for authority.
145  get_control_plane_credentials(const char* authority);
146 
147  const char* type() const { return type_; }
148 
149  private:
150  const char* type_;
151  std::map<grpc_core::UniquePtr<char>,
154  local_control_plane_creds_;
155 };
156 
157 /* Util to encapsulate the channel credentials in a channel arg. */
159 
160 /* Util to get the channel credentials from a channel arg. */
162  const grpc_arg* arg);
163 
164 /* Util to find the channel credentials from channel args. */
166  const grpc_channel_args* args);
167 
177  grpc_channel_credentials* credentials, const char* authority,
178  grpc_channel_credentials* control_plane_creds);
179 
185  const char* authority, grpc_channel_credentials* control_plane_creds);
186 
187 /* Initializes global control plane credentials data. */
189 
190 /* Test only: destroy global control plane credentials data.
191  * This API is meant for use by a few tests that need to
192  * satisdy grpc_core::LeakDetector. */
194 
195 /* Test only: force re-initialization of global control
196  * plane credentials data if it was previously destroyed.
197  * This API is meant to be used in
198  * tandem with the
199  * grpc_test_only_control_plane_credentials_destroy, for
200  * the few tests that need it. */
202 
203 /* --- grpc_credentials_mdelem_array. --- */
204 
205 typedef struct {
206  grpc_mdelem* md = nullptr;
207  size_t size = 0;
209 
212  grpc_mdelem md);
213 
217 
219 
220 /* --- grpc_call_credentials. --- */
221 
222 // This type is forward declared as a C struct and we cannot define it as a
223 // class. Otherwise, compiler will complain about type mismatch due to
224 // -Wmismatched-tags.
226  : public grpc_core::RefCounted<grpc_call_credentials> {
227  public:
228  explicit grpc_call_credentials(const char* type) : type_(type) {}
229  virtual ~grpc_call_credentials() = default;
230 
231  // Returns true if completed synchronously, in which case \a error will
232  // be set to indicate the result. Otherwise, \a on_request_metadata will
233  // be invoked asynchronously when complete. \a md_array will be populated
234  // with the resulting metadata once complete.
238  grpc_closure* on_request_metadata,
239  grpc_error** error) = 0;
240 
241  // Cancels a pending asynchronous operation started by
242  // grpc_call_credentials_get_request_metadata() with the corresponding
243  // value of \a md_array.
245  grpc_credentials_mdelem_array* md_array, grpc_error* error) = 0;
246 
247  const char* type() const { return type_; }
248 
249  private:
250  const char* type_;
251 };
252 
253 /* Metadata-only credentials with the specified key and value where
254  asynchronicity can be simulated for testing. */
256  const char* md_key, const char* md_value, bool is_async);
257 
258 /* --- grpc_server_credentials. --- */
259 
260 // This type is forward declared as a C struct and we cannot define it as a
261 // class. Otherwise, compiler will complain about type mismatch due to
262 // -Wmismatched-tags.
264  : public grpc_core::RefCounted<grpc_server_credentials> {
265  public:
266  explicit grpc_server_credentials(const char* type) : type_(type) {}
267 
268  virtual ~grpc_server_credentials() { DestroyProcessor(); }
269 
272 
273  const char* type() const { return type_; }
274 
276  return processor_;
277  }
279  const grpc_auth_metadata_processor& processor);
280 
281  private:
282  void DestroyProcessor() {
283  if (processor_.destroy != nullptr && processor_.state != nullptr) {
284  processor_.destroy(processor_.state);
285  }
286  }
287 
288  const char* type_;
289  grpc_auth_metadata_processor processor_ =
290  grpc_auth_metadata_processor(); // Zero-initialize the C struct.
291 };
292 
293 #define GRPC_SERVER_CREDENTIALS_ARG "grpc.server_credentials"
294 
298  const grpc_channel_args* args);
299 
300 /* -- Credentials Metadata Request. -- */
301 
305  : creds(std::move(creds)) {}
308  }
309 
312 };
313 
317  return new grpc_credentials_metadata_request(std::move(creds));
318 }
319 
322  delete r;
323 }
324 
325 #endif /* GRPC_CORE_LIB_SECURITY_CREDENTIALS_CREDENTIALS_H */
Definition: ref_counted.h:248
RefCountedPtr< grpc_channel_credentials > Ref() GRPC_MUST_USE_RESULT
Definition: ref_counted.h:253
Definition: ref_counted_ptr.h:35
char *(* grpc_well_known_credentials_path_getter)(void)
Definition: credentials.h:88
grpc_channel_credentials * grpc_channel_credentials_find_in_args(const grpc_channel_args *args)
Definition: credentials.cc:170
grpc_channel_credentials * grpc_channel_credentials_from_arg(const grpc_arg *arg)
Definition: credentials.cc:159
grpc_arg grpc_channel_credentials_to_arg(grpc_channel_credentials *credentials)
Definition: credentials.cc:152
grpc_credentials_status
Definition: credentials.h:41
@ GRPC_CREDENTIALS_OK
Definition: credentials.h:42
@ GRPC_CREDENTIALS_ERROR
Definition: credentials.h:43
void grpc_credentials_mdelem_array_add(grpc_credentials_mdelem_array *list, grpc_mdelem md)
Takes a new ref to md.
Definition: credentials_metadata.cc:42
char * grpc_get_well_known_google_credentials_file_path(void)
Definition: google_default_credentials.cc:378
grpc_arg grpc_server_credentials_to_arg(grpc_server_credentials *c)
Definition: credentials.cc:221
void grpc_control_plane_credentials_init()
Definition: credentials.cc:62
void grpc_credentials_mdelem_array_append(grpc_credentials_mdelem_array *dst, grpc_credentials_mdelem_array *src)
Appends all elements from src to dst, taking a new ref to each one.
Definition: credentials_metadata.cc:48
grpc_server_credentials * grpc_find_server_credentials_in_args(const grpc_channel_args *args)
Definition: credentials.cc:236
char * grpc_get_well_known_google_credentials_file_path_impl(void)
Definition: credentials_generic.cc:30
void grpc_override_well_known_credentials_path_getter(grpc_well_known_credentials_path_getter getter)
Definition: google_default_credentials.cc:383
bool grpc_channel_credentials_attach_credentials(grpc_channel_credentials *credentials, const char *authority, grpc_channel_credentials *control_plane_creds)
EXPERIMENTAL.
Definition: credentials.cc:79
void grpc_test_only_control_plane_credentials_destroy()
Definition: credentials.cc:67
void grpc_credentials_mdelem_array_destroy(grpc_credentials_mdelem_array *list)
Definition: credentials_metadata.cc:56
void grpc_credentials_metadata_request_destroy(grpc_credentials_metadata_request *r)
Definition: credentials.h:320
void grpc_test_only_control_plane_credentials_force_init()
Definition: credentials.cc:73
grpc_credentials_metadata_request * grpc_credentials_metadata_request_create(grpc_core::RefCountedPtr< grpc_call_credentials > creds)
Definition: credentials.h:315
grpc_call_credentials * grpc_md_only_test_credentials_create(const char *md_key, const char *md_value, bool is_async)
Definition: fake_credentials.cc:109
grpc_server_credentials * grpc_server_credentials_from_arg(const grpc_arg *arg)
Definition: credentials.cc:226
bool grpc_control_plane_credentials_register(const char *authority, grpc_channel_credentials *control_plane_creds)
EXPERIMENTAL.
Definition: credentials.cc:86
void grpc_http_response_destroy(grpc_http_response *response)
Definition: parser.cc:344
A single argument...
Definition: grpc_types.h:103
Context that can be used by metadata credentials plugin in order to create auth related metadata.
Definition: grpc_security.h:373
Pluggable server-side metadata processor object.
Definition: grpc_security.h:592
void(* destroy)(void *state)
Definition: grpc_security.h:600
void * state
Definition: grpc_security.h:601
Definition: credentials.h:226
virtual void cancel_get_request_metadata(grpc_credentials_mdelem_array *md_array, grpc_error *error)=0
const char * type() const
Definition: credentials.h:247
virtual ~grpc_call_credentials()=default
virtual bool get_request_metadata(grpc_polling_entity *pollent, grpc_auth_metadata_context context, grpc_credentials_mdelem_array *md_array, grpc_closure *on_request_metadata, grpc_error **error)=0
grpc_call_credentials(const char *type)
Definition: credentials.h:228
An array of arguments that can be passed around.
Definition: grpc_types.h:132
Definition: credentials.h:100
virtual grpc_core::RefCountedPtr< grpc_channel_credentials > duplicate_without_call_credentials()
Definition: credentials.h:119
grpc_channel_credentials(const char *type)
Definition: credentials.h:102
grpc_core::RefCountedPtr< grpc_channel_credentials > get_control_plane_credentials(const char *authority)
Definition: credentials.cc:114
virtual ~grpc_channel_credentials()=default
const char * type() const
Definition: credentials.h:147
virtual grpc_channel_args * update_arguments(grpc_channel_args *args)
Definition: credentials.h:128
bool attach_credentials(const char *authority, grpc_core::RefCountedPtr< grpc_channel_credentials > control_plane_creds)
Definition: credentials.cc:101
virtual grpc_core::RefCountedPtr< grpc_channel_security_connector > create_security_connector(grpc_core::RefCountedPtr< grpc_call_credentials > call_creds, const char *target, const grpc_channel_args *args, grpc_channel_args **new_args)=0
A closure over a grpc_iomgr_cb_func.
Definition: closure.h:56
Definition: map.h:33
Definition: credentials.h:205
Definition: credentials.h:302
grpc_http_response response
Definition: credentials.h:311
~grpc_credentials_metadata_request()
Definition: credentials.h:306
grpc_credentials_metadata_request(grpc_core::RefCountedPtr< grpc_call_credentials > creds)
Definition: credentials.h:303
grpc_core::RefCountedPtr< grpc_call_credentials > creds
Definition: credentials.h:310
Definition: error_internal.h:39
Definition: parser.h:71
Definition: metadata.h:98
Definition: polling_entity.h:37
Definition: credentials.h:264
const grpc_auth_metadata_processor & auth_metadata_processor() const
Definition: credentials.h:275
virtual grpc_core::RefCountedPtr< grpc_server_security_connector > create_security_connector()=0
grpc_server_credentials(const char *type)
Definition: credentials.h:266
const char * type() const
Definition: credentials.h:273
virtual ~grpc_server_credentials()
Definition: credentials.h:268
void set_auth_metadata_processor(const grpc_auth_metadata_processor &processor)
Definition: credentials.cc:188