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_GRPC_SECURITY_H
20#define GRPC_GRPC_SECURITY_H
21
22#include <grpc/support/port_platform.h>
23
24#include <grpc/grpc.h>
25#include <grpc/grpc_security_constants.h>
26#include <grpc/status.h>
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32/** --- Authentication Context. --- */
33
34typedef struct grpc_auth_context grpc_auth_context;
35
36typedef struct grpc_auth_property_iterator {
37 const grpc_auth_context* ctx;
38 size_t index;
39 const char* name;
40} grpc_auth_property_iterator;
41
42/** value, if not NULL, is guaranteed to be NULL terminated. */
43typedef struct grpc_auth_property {
44 char* name;
45 char* value;
46 size_t value_length;
47} grpc_auth_property;
48
49/** Returns NULL when the iterator is at the end. */
50GRPCAPI const grpc_auth_property* grpc_auth_property_iterator_next(
51 grpc_auth_property_iterator* it);
52
53/** Iterates over the auth context. */
54GRPCAPI grpc_auth_property_iterator
55grpc_auth_context_property_iterator(const grpc_auth_context* ctx);
56
57/** Gets the peer identity. Returns an empty iterator (first _next will return
58 NULL) if the peer is not authenticated. */
59GRPCAPI grpc_auth_property_iterator
60grpc_auth_context_peer_identity(const grpc_auth_context* ctx);
61
62/** Finds a property in the context. May return an empty iterator (first _next
63 will return NULL) if no property with this name was found in the context. */
64GRPCAPI grpc_auth_property_iterator grpc_auth_context_find_properties_by_name(
65 const grpc_auth_context* ctx, const char* name);
66
67/** Gets the name of the property that indicates the peer identity. Will return
68 NULL if the peer is not authenticated. */
69GRPCAPI const char* grpc_auth_context_peer_identity_property_name(
70 const grpc_auth_context* ctx);
71
72/** Returns 1 if the peer is authenticated, 0 otherwise. */
73GRPCAPI int grpc_auth_context_peer_is_authenticated(
74 const grpc_auth_context* ctx);
75
76/** Gets the auth context from the call. Caller needs to call
77 grpc_auth_context_release on the returned context. */
78GRPCAPI grpc_auth_context* grpc_call_auth_context(grpc_call* call);
79
80/** Releases the auth context returned from grpc_call_auth_context. */
81GRPCAPI void grpc_auth_context_release(grpc_auth_context* context);
82
83/** --
84 The following auth context methods should only be called by a server metadata
85 processor to set properties extracted from auth metadata.
86 -- */
87
88/** Add a property. */
89GRPCAPI void grpc_auth_context_add_property(grpc_auth_context* ctx,
90 const char* name, const char* value,
91 size_t value_length);
92
93/** Add a C string property. */
94GRPCAPI void grpc_auth_context_add_cstring_property(grpc_auth_context* ctx,
95 const char* name,
96 const char* value);
97
98/** Sets the property name. Returns 1 if successful or 0 in case of failure
99 (which means that no property with this name exists). */
100GRPCAPI int grpc_auth_context_set_peer_identity_property_name(
101 grpc_auth_context* ctx, const char* name);
102
103/** --- SSL Session Cache. ---
104
105 A SSL session cache object represents a way to cache client sessions
106 between connections. Only ticket-based resumption is supported. */
107
108typedef struct grpc_ssl_session_cache grpc_ssl_session_cache;
109
110/** Create LRU cache for client-side SSL sessions with the given capacity.
111 If capacity is < 1, a default capacity is used instead. */
112GRPCAPI grpc_ssl_session_cache* grpc_ssl_session_cache_create_lru(
113 size_t capacity);
114
115/** Destroy SSL session cache. */
116GRPCAPI void grpc_ssl_session_cache_destroy(grpc_ssl_session_cache* cache);
117
118/** Create a channel arg with the given cache object. */
119GRPCAPI grpc_arg
120grpc_ssl_session_cache_create_channel_arg(grpc_ssl_session_cache* cache);
121
122/** --- grpc_call_credentials object.
123
124 A call credentials object represents a way to authenticate on a particular
125 call. These credentials can be composed with a channel credentials object
126 so that they are sent with every call on this channel. */
127
128typedef struct grpc_call_credentials grpc_call_credentials;
129
130/** Releases a call credentials object.
131 The creator of the credentials object is responsible for its release. */
132GRPCAPI void grpc_call_credentials_release(grpc_call_credentials* creds);
133
134/** Creates default credentials to connect to a google gRPC service.
135 WARNING: Do NOT use this credentials to connect to a non-google service as
136 this could result in an oauth2 token leak. The security level of the
137 resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
138
139 If specified, the supplied call credentials object will be attached to the
140 returned channel credentials object. The call_credentials object must remain
141 valid throughout the lifetime of the returned grpc_channel_credentials
142 object. It is expected that the call credentials object was generated
143 according to the Application Default Credentials mechanism and asserts the
144 identity of the default service account of the machine. Supplying any other
145 sort of call credential will result in undefined behavior, up to and
146 including the sudden and unexpected failure of RPCs.
147
148 If nullptr is supplied, the returned channel credentials object will use a
149 call credentials object based on the Application Default Credentials
150 mechanism.
151*/
152GRPCAPI grpc_channel_credentials* grpc_google_default_credentials_create(
153 grpc_call_credentials* call_credentials);
154
155/** Callback for getting the SSL roots override from the application.
156 In case of success, *pem_roots_certs must be set to a NULL terminated string
157 containing the list of PEM encoded root certificates. The ownership is passed
158 to the core and freed (laster by the core) with gpr_free.
159 If this function fails and GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is
160 set to a valid path, it will override the roots specified this func */
161typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)(
162 char** pem_root_certs);
163
164/** Setup a callback to override the default TLS/SSL roots.
165 This function is not thread-safe and must be called at initialization time
166 before any ssl credentials are created to have the desired side effect.
167 If GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, the
168 callback will not be called. */
169GRPCAPI void grpc_set_ssl_roots_override_callback(
170 grpc_ssl_roots_override_callback cb);
171
172/** Object that holds a private key / certificate chain pair in PEM format. */
173typedef struct {
174 /** private_key is the NULL-terminated string containing the PEM encoding of
175 the client's private key. */
176 const char* private_key;
177
178 /** cert_chain is the NULL-terminated string containing the PEM encoding of
179 the client's certificate chain. */
180 const char* cert_chain;
181} grpc_ssl_pem_key_cert_pair;
182
183/** Deprecated in favor of grpc_ssl_verify_peer_options. It will be removed
184 after all of its call sites are migrated to grpc_ssl_verify_peer_options.
185 Object that holds additional peer-verification options on a secure
186 channel. */
187typedef struct {
188 /** If non-NULL this callback will be invoked with the expected
189 target_name, the peer's certificate (in PEM format), and whatever
190 userdata pointer is set below. If a non-zero value is returned by this
191 callback then it is treated as a verification failure. Invocation of
192 the callback is blocking, so any implementation should be light-weight.
193 */
194 int (*verify_peer_callback)(const char* target_name, const char* peer_pem,
195 void* userdata);
196 /** Arbitrary userdata that will be passed as the last argument to
197 verify_peer_callback. */
198 void* verify_peer_callback_userdata;
199 /** A destruct callback that will be invoked when the channel is being
200 cleaned up. The userdata argument will be passed to it. The intent is
201 to perform any cleanup associated with that userdata. */
202 void (*verify_peer_destruct)(void* userdata);
203} verify_peer_options;
204
205/** Object that holds additional peer-verification options on a secure
206 channel. */
207typedef struct {
208 /** If non-NULL this callback will be invoked with the expected
209 target_name, the peer's certificate (in PEM format), and whatever
210 userdata pointer is set below. If a non-zero value is returned by this
211 callback then it is treated as a verification failure. Invocation of
212 the callback is blocking, so any implementation should be light-weight.
213 */
214 int (*verify_peer_callback)(const char* target_name, const char* peer_pem,
215 void* userdata);
216 /** Arbitrary userdata that will be passed as the last argument to
217 verify_peer_callback. */
218 void* verify_peer_callback_userdata;
219 /** A destruct callback that will be invoked when the channel is being
220 cleaned up. The userdata argument will be passed to it. The intent is
221 to perform any cleanup associated with that userdata. */
222 void (*verify_peer_destruct)(void* userdata);
223} grpc_ssl_verify_peer_options;
224
225/** Deprecated in favor of grpc_ssl_server_credentials_create_ex. It will be
226 removed after all of its call sites are migrated to
227 grpc_ssl_server_credentials_create_ex. Creates an SSL credentials object.
228 The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
229 - pem_root_certs is the NULL-terminated string containing the PEM encoding
230 of the server root certificates. If this parameter is NULL, the
231 implementation will first try to dereference the file pointed by the
232 GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails,
233 try to get the roots set by grpc_override_ssl_default_roots. Eventually,
234 if all these fail, it will try to get the roots from a well-known place on
235 disk (in the grpc install directory).
236
237 gRPC has implemented root cache if the underlying OpenSSL library supports
238 it. The gRPC root certificates cache is only applicable on the default
239 root certificates, which is used when this parameter is nullptr. If user
240 provides their own pem_root_certs, when creating an SSL credential object,
241 gRPC would not be able to cache it, and each subchannel will generate a
242 copy of the root store. So it is recommended to avoid providing large room
243 pem with pem_root_certs parameter to avoid excessive memory consumption,
244 particularly on mobile platforms such as iOS.
245 - pem_key_cert_pair is a pointer on the object containing client's private
246 key and certificate chain. This parameter can be NULL if the client does
247 not have such a key/cert pair.
248 - verify_options is an optional verify_peer_options object which holds
249 additional options controlling how peer certificates are verified. For
250 example, you can supply a callback which receives the peer's certificate
251 with which you can do additional verification. Can be NULL, in which
252 case verification will retain default behavior. Any settings in
253 verify_options are copied during this call, so the verify_options
254 object can be released afterwards. */
255GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create(
256 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pair,
257 const verify_peer_options* verify_options, void* reserved);
258
259/* Creates an SSL credentials object.
260 The security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
261 - pem_root_certs is the NULL-terminated string containing the PEM encoding
262 of the server root certificates. If this parameter is NULL, the
263 implementation will first try to dereference the file pointed by the
264 GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable, and if that fails,
265 try to get the roots set by grpc_override_ssl_default_roots. Eventually,
266 if all these fail, it will try to get the roots from a well-known place on
267 disk (in the grpc install directory).
268
269 gRPC has implemented root cache if the underlying OpenSSL library supports
270 it. The gRPC root certificates cache is only applicable on the default
271 root certificates, which is used when this parameter is nullptr. If user
272 provides their own pem_root_certs, when creating an SSL credential object,
273 gRPC would not be able to cache it, and each subchannel will generate a
274 copy of the root store. So it is recommended to avoid providing large room
275 pem with pem_root_certs parameter to avoid excessive memory consumption,
276 particularly on mobile platforms such as iOS.
277 - pem_key_cert_pair is a pointer on the object containing client's private
278 key and certificate chain. This parameter can be NULL if the client does
279 not have such a key/cert pair.
280 - verify_options is an optional verify_peer_options object which holds
281 additional options controlling how peer certificates are verified. For
282 example, you can supply a callback which receives the peer's certificate
283 with which you can do additional verification. Can be NULL, in which
284 case verification will retain default behavior. Any settings in
285 verify_options are copied during this call, so the verify_options
286 object can be released afterwards. */
287GRPCAPI grpc_channel_credentials* grpc_ssl_credentials_create_ex(
288 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pair,
289 const grpc_ssl_verify_peer_options* verify_options, void* reserved);
290
291/** Creates a composite channel credentials object. The security level of
292 * resulting connection is determined by channel_creds. */
293GRPCAPI grpc_channel_credentials* grpc_composite_channel_credentials_create(
294 grpc_channel_credentials* channel_creds, grpc_call_credentials* call_creds,
295 void* reserved);
296
297/** --- composite credentials. */
298
299/** Creates a composite call credentials object. */
300GRPCAPI grpc_call_credentials* grpc_composite_call_credentials_create(
301 grpc_call_credentials* creds1, grpc_call_credentials* creds2,
302 void* reserved);
303
304/** Creates a compute engine credentials object for connecting to Google.
305 WARNING: Do NOT use this credentials to connect to a non-google service as
306 this could result in an oauth2 token leak. */
307GRPCAPI grpc_call_credentials* grpc_google_compute_engine_credentials_create(
308 void* reserved);
309
310GRPCAPI gpr_timespec grpc_max_auth_token_lifetime(void);
311
312/** Creates a JWT credentials object. May return NULL if the input is invalid.
313 - json_key is the JSON key string containing the client's private key.
314 - token_lifetime is the lifetime of each Json Web Token (JWT) created with
315 this credentials. It should not exceed grpc_max_auth_token_lifetime or
316 will be cropped to this value. */
317GRPCAPI grpc_call_credentials*
318grpc_service_account_jwt_access_credentials_create(const char* json_key,
319 gpr_timespec token_lifetime,
320 void* reserved);
321
322/** Builds External Account credentials.
323 - json_string is the JSON string containing the credentials options.
324 - scopes_string contains the scopes to be binded with the credentials.
325 This API is used for experimental purposes for now and may change in the
326 future. */
327GRPCAPI grpc_call_credentials* grpc_external_account_credentials_create(
328 const char* json_string, const char* scopes_string);
329
330/** Creates an Oauth2 Refresh Token credentials object for connecting to Google.
331 May return NULL if the input is invalid.
332 WARNING: Do NOT use this credentials to connect to a non-google service as
333 this could result in an oauth2 token leak.
334 - json_refresh_token is the JSON string containing the refresh token itself
335 along with a client_id and client_secret. */
336GRPCAPI grpc_call_credentials* grpc_google_refresh_token_credentials_create(
337 const char* json_refresh_token, void* reserved);
338
339/** Creates an Oauth2 Access Token credentials with an access token that was
340 acquired by an out of band mechanism. */
341GRPCAPI grpc_call_credentials* grpc_access_token_credentials_create(
342 const char* access_token, void* reserved);
343
344/** Creates an IAM credentials object for connecting to Google. */
345GRPCAPI grpc_call_credentials* grpc_google_iam_credentials_create(
346 const char* authorization_token, const char* authority_selector,
347 void* reserved);
348
349/** Options for creating STS Oauth Token Exchange credentials following the IETF
350 draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
351 Optional fields may be set to NULL or empty string. It is the responsibility
352 of the caller to ensure that the subject and actor tokens are refreshed on
353 disk at the specified paths. This API is used for experimental purposes for
354 now and may change in the future. */
355typedef struct {
356 const char* token_exchange_service_uri; /* Required. */
357 const char* resource; /* Optional. */
358 const char* audience; /* Optional. */
359 const char* scope; /* Optional. */
360 const char* requested_token_type; /* Optional. */
361 const char* subject_token_path; /* Required. */
362 const char* subject_token_type; /* Required. */
363 const char* actor_token_path; /* Optional. */
364 const char* actor_token_type; /* Optional. */
365} grpc_sts_credentials_options;
366
367/** Creates an STS credentials following the STS Token Exchanged specifed in the
368 IETF draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
369 This API is used for experimental purposes for now and may change in the
370 future. */
371GRPCAPI grpc_call_credentials* grpc_sts_credentials_create(
372 const grpc_sts_credentials_options* options, void* reserved);
373
374/** Callback function to be called by the metadata credentials plugin
375 implementation when the metadata is ready.
376 - user_data is the opaque pointer that was passed in the get_metadata method
377 of the grpc_metadata_credentials_plugin (see below).
378 - creds_md is an array of credentials metadata produced by the plugin. It
379 may be set to NULL in case of an error.
380 - num_creds_md is the number of items in the creds_md array.
381 - status must be GRPC_STATUS_OK in case of success or another specific error
382 code otherwise.
383 - error_details contains details about the error if any. In case of success
384 it should be NULL and will be otherwise ignored. */
385typedef void (*grpc_credentials_plugin_metadata_cb)(
386 void* user_data, const grpc_metadata* creds_md, size_t num_creds_md,
387 grpc_status_code status, const char* error_details);
388
389/** Context that can be used by metadata credentials plugin in order to create
390 auth related metadata. */
391typedef struct {
392 /** The fully qualifed service url. */
393 const char* service_url;
394
395 /** The method name of the RPC being called (not fully qualified).
396 The fully qualified method name can be built from the service_url:
397 full_qualified_method_name = ctx->service_url + '/' + ctx->method_name. */
398 const char* method_name;
399
400 /** The auth_context of the channel which gives the server's identity. */
401 const grpc_auth_context* channel_auth_context;
402
403 /** Reserved for future use. */
404 void* reserved;
405} grpc_auth_metadata_context;
406
407/** Performs a deep copy from \a from to \a to. **/
408GRPCAPI void grpc_auth_metadata_context_copy(grpc_auth_metadata_context* from,
409 grpc_auth_metadata_context* to);
410
411/** Releases internal resources held by \a context. **/
412GRPCAPI void grpc_auth_metadata_context_reset(
413 grpc_auth_metadata_context* context);
414
415/** Maximum number of metadata entries returnable by a credentials plugin via
416 a synchronous return. */
417#define GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX 4
418
419/** grpc_metadata_credentials plugin is an API user provided structure used to
420 create grpc_credentials objects that can be set on a channel (composed) or
421 a call. See grpc_credentials_metadata_create_from_plugin below.
422 The grpc client stack will call the get_metadata method of the plugin for
423 every call in scope for the credentials created from it. */
424typedef struct {
425 /** The implementation of this method has to be non-blocking, but can
426 be performed synchronously or asynchronously.
427
428 If processing occurs synchronously, returns non-zero and populates
429 creds_md, num_creds_md, status, and error_details. In this case,
430 the caller takes ownership of the entries in creds_md and of
431 error_details. Note that if the plugin needs to return more than
432 GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX entries in creds_md, it must
433 return asynchronously.
434
435 If processing occurs asynchronously, returns zero and invokes \a cb
436 when processing is completed. \a user_data will be passed as the
437 first parameter of the callback. NOTE: \a cb MUST be invoked in a
438 different thread, not from the thread in which \a get_metadata() is
439 invoked.
440
441 \a context is the information that can be used by the plugin to create
442 auth metadata. */
443 int (*get_metadata)(
444 void* state, grpc_auth_metadata_context context,
445 grpc_credentials_plugin_metadata_cb cb, void* user_data,
446 grpc_metadata creds_md[GRPC_METADATA_CREDENTIALS_PLUGIN_SYNC_MAX],
447 size_t* num_creds_md, grpc_status_code* status,
448 const char** error_details);
449
450 /** Implements debug string of the given plugin. This method returns an
451 * allocated string that the caller needs to free using gpr_free() */
452 char* (*debug_string)(void* state);
453
454 /** Destroys the plugin state. */
455 void (*destroy)(void* state);
456
457 /** State that will be set as the first parameter of the methods above. */
458 void* state;
459
460 /** Type of credentials that this plugin is implementing. */
461 const char* type;
462} grpc_metadata_credentials_plugin;
463
464/** Creates a credentials object from a plugin with a specified minimum security
465 * level. */
466GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin(
467 grpc_metadata_credentials_plugin plugin,
468 grpc_security_level min_security_level, void* reserved);
469
470/** Server certificate config object holds the server's public certificates and
471 associated private keys, as well as any CA certificates needed for client
472 certificate validation (if applicable). Create using
473 grpc_ssl_server_certificate_config_create(). */
474typedef struct grpc_ssl_server_certificate_config
475 grpc_ssl_server_certificate_config;
476
477/** Creates a grpc_ssl_server_certificate_config object.
478 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of
479 the client root certificates. This parameter may be NULL if the server does
480 not want the client to be authenticated with SSL.
481 - pem_key_cert_pairs is an array private key / certificate chains of the
482 server. This parameter cannot be NULL.
483 - num_key_cert_pairs indicates the number of items in the private_key_files
484 and cert_chain_files parameters. It must be at least 1.
485 - It is the caller's responsibility to free this object via
486 grpc_ssl_server_certificate_config_destroy(). */
487GRPCAPI grpc_ssl_server_certificate_config*
488grpc_ssl_server_certificate_config_create(
489 const char* pem_root_certs,
490 const grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs,
491 size_t num_key_cert_pairs);
492
493/** Destroys a grpc_ssl_server_certificate_config object. */
494GRPCAPI void grpc_ssl_server_certificate_config_destroy(
495 grpc_ssl_server_certificate_config* config);
496
497/** Callback to retrieve updated SSL server certificates, private keys, and
498 trusted CAs (for client authentication).
499 - user_data parameter, if not NULL, contains opaque data to be used by the
500 callback.
501 - Use grpc_ssl_server_certificate_config_create to create the config.
502 - The caller assumes ownership of the config. */
503typedef grpc_ssl_certificate_config_reload_status (
504 *grpc_ssl_server_certificate_config_callback)(
505 void* user_data, grpc_ssl_server_certificate_config** config);
506
507/** Deprecated in favor of grpc_ssl_server_credentials_create_ex.
508 Creates an SSL server_credentials object.
509 - pem_roots_cert is the NULL-terminated string containing the PEM encoding of
510 the client root certificates. This parameter may be NULL if the server does
511 not want the client to be authenticated with SSL.
512 - pem_key_cert_pairs is an array private key / certificate chains of the
513 server. This parameter cannot be NULL.
514 - num_key_cert_pairs indicates the number of items in the private_key_files
515 and cert_chain_files parameters. It should be at least 1.
516 - force_client_auth, if set to non-zero will force the client to authenticate
517 with an SSL cert. Note that this option is ignored if pem_root_certs is
518 NULL. */
519GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create(
520 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs,
521 size_t num_key_cert_pairs, int force_client_auth, void* reserved);
522
523/** Deprecated in favor of grpc_ssl_server_credentials_create_with_options.
524 Same as grpc_ssl_server_credentials_create method except uses
525 grpc_ssl_client_certificate_request_type enum to support more ways to
526 authenticate client certificates.*/
527GRPCAPI grpc_server_credentials* grpc_ssl_server_credentials_create_ex(
528 const char* pem_root_certs, grpc_ssl_pem_key_cert_pair* pem_key_cert_pairs,
529 size_t num_key_cert_pairs,
530 grpc_ssl_client_certificate_request_type client_certificate_request,
531 void* reserved);
532
533typedef struct grpc_ssl_server_credentials_options
534 grpc_ssl_server_credentials_options;
535
536/** Creates an options object using a certificate config. Use this method when
537 the certificates and keys of the SSL server will not change during the
538 server's lifetime.
539 - Takes ownership of the certificate_config parameter. */
540GRPCAPI grpc_ssl_server_credentials_options*
541grpc_ssl_server_credentials_create_options_using_config(
542 grpc_ssl_client_certificate_request_type client_certificate_request,
543 grpc_ssl_server_certificate_config* certificate_config);
544
545/** Creates an options object using a certificate config fetcher. Use this
546 method to reload the certificates and keys of the SSL server without
547 interrupting the operation of the server. Initial certificate config will be
548 fetched during server initialization.
549 - user_data parameter, if not NULL, contains opaque data which will be passed
550 to the fetcher (see definition of
551 grpc_ssl_server_certificate_config_callback). */
552GRPCAPI grpc_ssl_server_credentials_options*
553grpc_ssl_server_credentials_create_options_using_config_fetcher(
554 grpc_ssl_client_certificate_request_type client_certificate_request,
555 grpc_ssl_server_certificate_config_callback cb, void* user_data);
556
557/** Destroys a grpc_ssl_server_credentials_options object. */
558GRPCAPI void grpc_ssl_server_credentials_options_destroy(
559 grpc_ssl_server_credentials_options* options);
560
561/** Creates an SSL server_credentials object using the provided options struct.
562 - Takes ownership of the options parameter. */
563GRPCAPI grpc_server_credentials*
564grpc_ssl_server_credentials_create_with_options(
565 grpc_ssl_server_credentials_options* options);
566
567/** --- Call specific credentials. --- */
568
569/** Sets a credentials to a call. Can only be called on the client side before
570 grpc_call_start_batch. */
571GRPCAPI grpc_call_error grpc_call_set_credentials(grpc_call* call,
572 grpc_call_credentials* creds);
573
574/** --- Auth Metadata Processing --- */
575
576/** Callback function that is called when the metadata processing is done.
577 - Consumed metadata will be removed from the set of metadata available on the
578 call. consumed_md may be NULL if no metadata has been consumed.
579 - Response metadata will be set on the response. response_md may be NULL.
580 - status is GRPC_STATUS_OK for success or a specific status for an error.
581 Common error status for auth metadata processing is either
582 GRPC_STATUS_UNAUTHENTICATED in case of an authentication failure or
583 GRPC_STATUS PERMISSION_DENIED in case of an authorization failure.
584 - error_details gives details about the error. May be NULL. */
585typedef void (*grpc_process_auth_metadata_done_cb)(
586 void* user_data, const grpc_metadata* consumed_md, size_t num_consumed_md,
587 const grpc_metadata* response_md, size_t num_response_md,
588 grpc_status_code status, const char* error_details);
589
590/** Pluggable server-side metadata processor object. */
591typedef struct {
592 /** The context object is read/write: it contains the properties of the
593 channel peer and it is the job of the process function to augment it with
594 properties derived from the passed-in metadata.
595 The lifetime of these objects is guaranteed until cb is invoked. */
596 void (*process)(void* state, grpc_auth_context* context,
597 const grpc_metadata* md, size_t num_md,
598 grpc_process_auth_metadata_done_cb cb, void* user_data);
599 void (*destroy)(void* state);
600 void* state;
601} grpc_auth_metadata_processor;
602
603GRPCAPI void grpc_server_credentials_set_auth_metadata_processor(
604 grpc_server_credentials* creds, grpc_auth_metadata_processor processor);
605
606/** --- ALTS channel/server credentials --- **/
607
608/**
609 * Main interface for ALTS credentials options. The options will contain
610 * information that will be passed from grpc to TSI layer such as RPC protocol
611 * versions. ALTS client (channel) and server credentials will have their own
612 * implementation of this interface. The APIs listed in this header are
613 * thread-compatible. It is used for experimental purpose for now and subject
614 * to change.
615 */
616typedef struct grpc_alts_credentials_options grpc_alts_credentials_options;
617
618/**
619 * This method creates a grpc ALTS credentials client options instance.
620 * It is used for experimental purpose for now and subject to change.
621 */
622GRPCAPI grpc_alts_credentials_options*
623grpc_alts_credentials_client_options_create(void);
624
625/**
626 * This method creates a grpc ALTS credentials server options instance.
627 * It is used for experimental purpose for now and subject to change.
628 */
629GRPCAPI grpc_alts_credentials_options*
630grpc_alts_credentials_server_options_create(void);
631
632/**
633 * This method adds a target service account to grpc client's ALTS credentials
634 * options instance. It is used for experimental purpose for now and subject
635 * to change.
636 *
637 * - options: grpc ALTS credentials options instance.
638 * - service_account: service account of target endpoint.
639 */
640GRPCAPI void grpc_alts_credentials_client_options_add_target_service_account(
641 grpc_alts_credentials_options* options, const char* service_account);
642
643/**
644 * This method destroys a grpc_alts_credentials_options instance by
645 * de-allocating all of its occupied memory. It is used for experimental purpose
646 * for now and subject to change.
647 *
648 * - options: a grpc_alts_credentials_options instance that needs to be
649 * destroyed.
650 */
651GRPCAPI void grpc_alts_credentials_options_destroy(
652 grpc_alts_credentials_options* options);
653
654/**
655 * This method creates an ALTS channel credential object. The security
656 * level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
657 * It is used for experimental purpose for now and subject to change.
658 *
659 * - options: grpc ALTS credentials options instance for client.
660 *
661 * It returns the created ALTS channel credential object.
662 */
663GRPCAPI grpc_channel_credentials* grpc_alts_credentials_create(
664 const grpc_alts_credentials_options* options);
665
666/**
667 * This method creates an ALTS server credential object. It is used for
668 * experimental purpose for now and subject to change.
669 *
670 * - options: grpc ALTS credentials options instance for server.
671 *
672 * It returns the created ALTS server credential object.
673 */
674GRPCAPI grpc_server_credentials* grpc_alts_server_credentials_create(
675 const grpc_alts_credentials_options* options);
676
677/** --- Local channel/server credentials --- **/
678
679/**
680 * This method creates a local channel credential object. The security level
681 * of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY for UDS and
682 * GRPC_SECURITY_NONE for LOCAL_TCP. It is used for experimental purpose
683 * for now and subject to change.
684 *
685 * - type: local connection type
686 *
687 * It returns the created local channel credential object.
688 */
689GRPCAPI grpc_channel_credentials* grpc_local_credentials_create(
690 grpc_local_connect_type type);
691
692/**
693 * This method creates a local server credential object. It is used for
694 * experimental purpose for now and subject to change.
695 *
696 * - type: local connection type
697 *
698 * It returns the created local server credential object.
699 */
700GRPCAPI grpc_server_credentials* grpc_local_server_credentials_create(
701 grpc_local_connect_type type);
702
703/** --- TLS channel/server credentials ---
704 * It is used for experimental purpose for now and subject to change. */
705
706/**
707 * EXPERIMENTAL API - Subject to change
708 *
709 * A struct that can be specified by callers to configure underlying TLS
710 * behaviors.
711 */
712typedef struct grpc_tls_credentials_options grpc_tls_credentials_options;
713
714/**
715 * EXPERIMENTAL API - Subject to change
716 *
717 * A struct provides ways to gain credential data that will be used in the TLS
718 * handshake.
719 */
720typedef struct grpc_tls_certificate_provider grpc_tls_certificate_provider;
721
722/**
723 * EXPERIMENTAL API - Subject to change
724 *
725 * A struct that stores the credential data presented to the peer in handshake
726 * to show local identity.
727 */
728typedef struct grpc_tls_identity_pairs grpc_tls_identity_pairs;
729
730/**
731 * EXPERIMENTAL API - Subject to change
732 *
733 * Creates a grpc_tls_identity_pairs that stores a list of identity credential
734 * data, including identity private key and identity certificate chain.
735 */
736GRPCAPI grpc_tls_identity_pairs* grpc_tls_identity_pairs_create();
737
738/**
739 * EXPERIMENTAL API - Subject to change
740 *
741 * Adds a identity private key and a identity certificate chain to
742 * grpc_tls_identity_pairs. This function will make an internal copy of
743 * |private_key| and |cert_chain|.
744 */
745GRPCAPI void grpc_tls_identity_pairs_add_pair(grpc_tls_identity_pairs* pairs,
746 const char* private_key,
747 const char* cert_chain);
748
749/**
750 * EXPERIMENTAL API - Subject to change
751 *
752 * Destroys a grpc_tls_identity_pairs object. If this object is passed to a
753 * provider initiation function, the ownership is transferred so this function
754 * doesn't need to be called. Otherwise the creator of the
755 * grpc_tls_identity_pairs object is responsible for its destruction.
756 */
757GRPCAPI void grpc_tls_identity_pairs_destroy(grpc_tls_identity_pairs* pairs);
758
759/**
760 * EXPERIMENTAL API - Subject to change
761 *
762 * Creates a grpc_tls_certificate_provider that will load credential data from
763 * static string during initialization. This provider will always return the
764 * same cert data for all cert names.
765 * root_certificate and pem_key_cert_pairs can be nullptr, indicating the
766 * corresponding credential data is not needed.
767 * This function will make a copy of |root_certificate|.
768 * The ownership of |pem_key_cert_pairs| is transferred.
769 */
770GRPCAPI grpc_tls_certificate_provider*
771grpc_tls_certificate_provider_static_data_create(
772 const char* root_certificate, grpc_tls_identity_pairs* pem_key_cert_pairs);
773
774/**
775 * EXPERIMENTAL API - Subject to change
776 *
777 * Creates a grpc_tls_certificate_provider that will watch the credential
778 * changes on the file system. This provider will always return the up-to-date
779 * cert data for all the cert names callers set through
780 * |grpc_tls_credentials_options|. Note that this API only supports one key-cert
781 * file and hence one set of identity key-cert pair, so SNI(Server Name
782 * Indication) is not supported.
783 * - private_key_path is the file path of the private key. This must be set if
784 * |identity_certificate_path| is set. Otherwise, it could be null if no
785 * identity credentials are needed.
786 * - identity_certificate_path is the file path of the identity certificate
787 * chain. This must be set if |private_key_path| is set. Otherwise, it could
788 * be null if no identity credentials are needed.
789 * - root_cert_path is the file path to the root certificate bundle. This
790 * may be null if no root certs are needed.
791 * - refresh_interval_sec is the refreshing interval that we will check the
792 * files for updates.
793 * It does not take ownership of parameters.
794 */
795GRPCAPI grpc_tls_certificate_provider*
796grpc_tls_certificate_provider_file_watcher_create(
797 const char* private_key_path, const char* identity_certificate_path,
798 const char* root_cert_path, unsigned int refresh_interval_sec);
799
800/**
801 * EXPERIMENTAL API - Subject to change
802 *
803 * Releases a grpc_tls_certificate_provider object. The creator of the
804 * grpc_tls_certificate_provider object is responsible for its release.
805 */
806GRPCAPI void grpc_tls_certificate_provider_release(
807 grpc_tls_certificate_provider* provider);
808
809/**
810 * EXPERIMENTAL API - Subject to change
811 *
812 * Creates an grpc_tls_credentials_options.
813 */
814GRPCAPI grpc_tls_credentials_options* grpc_tls_credentials_options_create(void);
815
816/**
817 * EXPERIMENTAL API - Subject to change
818 *
819 * Sets the credential provider in the options.
820 * The |options| will implicitly take a new ref to the |provider|.
821 */
822GRPCAPI void grpc_tls_credentials_options_set_certificate_provider(
823 grpc_tls_credentials_options* options,
824 grpc_tls_certificate_provider* provider);
825
826/**
827 * EXPERIMENTAL API - Subject to change
828 *
829 * If set, gRPC stack will keep watching the root certificates with
830 * name |root_cert_name|.
831 * If this is not set on the client side, we will use the root certificates
832 * stored in the default system location, since client side must provide root
833 * certificates in TLS.
834 * If this is not set on the server side, we will not watch any root certificate
835 * updates, and assume no root certificates needed for the server(single-side
836 * TLS). Default root certs on the server side is not supported.
837 */
838GRPCAPI void grpc_tls_credentials_options_watch_root_certs(
839 grpc_tls_credentials_options* options);
840
841/**
842 * EXPERIMENTAL API - Subject to change
843 *
844 * Sets the name of the root certificates being watched.
845 * If not set, We will use a default empty string as the root certificate name.
846 */
847GRPCAPI void grpc_tls_credentials_options_set_root_cert_name(
848 grpc_tls_credentials_options* options, const char* root_cert_name);
849
850/**
851 * EXPERIMENTAL API - Subject to change
852 *
853 * If set, gRPC stack will keep watching the identity key-cert pairs
854 * with name |identity_cert_name|.
855 * This is required on the server side, and optional on the client side.
856 */
857GRPCAPI void grpc_tls_credentials_options_watch_identity_key_cert_pairs(
858 grpc_tls_credentials_options* options);
859
860/**
861 * EXPERIMENTAL API - Subject to change
862 *
863 * Sets the name of the identity certificates being watched.
864 * If not set, We will use a default empty string as the identity certificate
865 * name.
866 */
867GRPCAPI void grpc_tls_credentials_options_set_identity_cert_name(
868 grpc_tls_credentials_options* options, const char* identity_cert_name);
869
870/**
871 * EXPERIMENTAL API - Subject to change
872 *
873 * Sets the options of whether to request and/or verify client certs. This shall
874 * only be called on the server side.
875 */
876GRPCAPI void grpc_tls_credentials_options_set_cert_request_type(
877 grpc_tls_credentials_options* options,
878 grpc_ssl_client_certificate_request_type type);
879/**
880 * EXPERIMENTAL API - Subject to change
881 *
882 * If set, gRPC will read all hashed x.509 CRL files in the directory and
883 * enforce the CRL files on all TLS handshakes. Only supported for OpenSSL
884 * version > 1.1.
885 * It is used for experimental purpose for now and subject to change.
886 */
887GRPCAPI void grpc_tls_credentials_options_set_crl_directory(
888 grpc_tls_credentials_options* options, const char* crl_directory);
889
890/**
891 * EXPERIMENTAL API - Subject to change
892 *
893 * Sets the options of whether to verify server certs on the client side.
894 * Passing in a non-zero value indicates verifying the certs.
895 */
896GRPCAPI void grpc_tls_credentials_options_set_verify_server_cert(
897 grpc_tls_credentials_options* options, int verify_server_cert);
898
899/**
900 * EXPERIMENTAL API - Subject to change
901 *
902 * The read-only request information exposed in a verification call.
903 * Callers should not directly manage the ownership of it. We will make sure it
904 * is always available inside verify() or cancel() call, and will destroy the
905 * object at the end of custom verification.
906 */
907typedef struct grpc_tls_custom_verification_check_request {
908 /* The target name of the server when the client initiates the connection. */
909 /* This field will be nullptr if on the server side. */
910 const char* target_name;
911 /* The information contained in the certificate chain sent from the peer. */
912 struct peer_info {
913 /* The Common Name field on the peer leaf certificate. */
914 const char* common_name;
915 /* The list of Subject Alternative Names on the peer leaf certificate. */
916 struct san_names {
917 char** uri_names;
918 size_t uri_names_size;
919 char** dns_names;
920 size_t dns_names_size;
921 char** email_names;
922 size_t email_names_size;
923 char** ip_names;
924 size_t ip_names_size;
925 } san_names;
926 /* The raw peer leaf certificate. */
927 const char* peer_cert;
928 /* The raw peer certificate chain. Note that it is not always guaranteed to
929 * get the peer full chain. For more, please refer to
930 * GRPC_X509_PEM_CERT_CHAIN_PROPERTY_NAME defined in file
931 * grpc_security_constants.h.
932 * TODO(ZhenLian): Consider fixing this in the future. */
933 const char* peer_cert_full_chain;
934 } peer_info;
935} grpc_tls_custom_verification_check_request;
936
937/**
938 * EXPERIMENTAL API - Subject to change
939 *
940 * A callback function provided by gRPC as a parameter of the |verify| function
941 * in grpc_tls_certificate_verifier_external. If |verify| is expected to be run
942 * asynchronously, the implementer of |verify| will need to invoke this callback
943 * with |callback_arg| and proper verification status at the end to bring the
944 * control back to gRPC C core.
945 */
946typedef void (*grpc_tls_on_custom_verification_check_done_cb)(
947 grpc_tls_custom_verification_check_request* request, void* callback_arg,
948 grpc_status_code status, const char* error_details);
949
950/**
951 * EXPERIMENTAL API - Subject to change
952 *
953 * The internal verifier type that will be used inside core.
954 */
955typedef struct grpc_tls_certificate_verifier grpc_tls_certificate_verifier;
956
957/**
958 * EXPERIMENTAL API - Subject to change
959 *
960 * A struct containing all the necessary functions a custom external verifier
961 * needs to implement to be able to be converted to an internal verifier.
962 */
963typedef struct grpc_tls_certificate_verifier_external {
964 void* user_data;
965 /**
966 * A function pointer containing the verification logic that will be
967 * performed after the TLS handshake is done. It could be processed
968 * synchronously or asynchronously.
969 * - If expected to be processed synchronously, the implementer should
970 * populate the verification result through |sync_status| and
971 * |sync_error_details|, and then return true.
972 * - If expected to be processed asynchronously, the implementer should return
973 * false immediately, and then in the asynchronous thread invoke |callback|
974 * with the verification result. The implementer MUST NOT invoke the async
975 * |callback| in the same thread before |verify| returns, otherwise it can
976 * lead to deadlocks.
977 *
978 * user_data: any argument that is passed in the user_data of
979 * grpc_tls_certificate_verifier_external during construction time
980 * can be retrieved later here.
981 * request: request information exposed to the function implementer.
982 * callback: the callback that the function implementer needs to invoke, if
983 * return a non-zero value. It is usually invoked when the
984 * asynchronous verification is done, and serves to bring the
985 * control back to gRPC.
986 * callback_arg: A pointer to the internal ExternalVerifier instance. This is
987 * mainly used as an argument in |callback|, if want to invoke
988 * |callback| in async mode.
989 * sync_status: indicates if a connection should be allowed. This should only
990 * be used if the verification check is done synchronously.
991 * sync_error_details: the error generated while verifying a connection. This
992 * should only be used if the verification check is done
993 * synchronously. the implementation must allocate the
994 * error string via gpr_malloc() or gpr_strdup().
995 * return: return 0 if |verify| is expected to be executed asynchronously,
996 * otherwise return a non-zero value.
997 */
998 int (*verify)(void* user_data,
999 grpc_tls_custom_verification_check_request* request,
1000 grpc_tls_on_custom_verification_check_done_cb callback,
1001 void* callback_arg, grpc_status_code* sync_status,
1002 char** sync_error_details);
1003 /**
1004 * A function pointer that cleans up the caller-specified resources when the
1005 * verifier is still running but the whole connection got cancelled. This
1006 * could happen when the verifier is doing some async operations, and the
1007 * whole handshaker object got destroyed because of connection time limit is
1008 * reached, or any other reasons. In such cases, function implementers might
1009 * want to be notified, and properly clean up some resources.
1010 *
1011 * user_data: any argument that is passed in the user_data of
1012 * grpc_tls_certificate_verifier_external during construction time
1013 * can be retrieved later here.
1014 * request: request information exposed to the function implementer. It will
1015 * be the same request object that was passed to verify(), and it
1016 * tells the cancel() which request to cancel.
1017 */
1018 void (*cancel)(void* user_data,
1019 grpc_tls_custom_verification_check_request* request);
1020 /**
1021 * A function pointer that does some additional destruction work when the
1022 * verifier is destroyed. This is used when the caller wants to associate some
1023 * objects to the lifetime of external_verifier, and destroy them when
1024 * external_verifier got destructed. For example, in C++, the class containing
1025 * user-specified callback functions should not be destroyed before
1026 * external_verifier, since external_verifier will invoke them while being
1027 * used.
1028 * Note that the caller MUST delete the grpc_tls_certificate_verifier_external
1029 * object itself in this function, otherwise it will cause memory leaks. That
1030 * also means the user_data has to carries at least a self pointer, for the
1031 * callers to later delete it in destruct().
1032 *
1033 * user_data: any argument that is passed in the user_data of
1034 * grpc_tls_certificate_verifier_external during construction time
1035 * can be retrieved later here.
1036 */
1037 void (*destruct)(void* user_data);
1038} grpc_tls_certificate_verifier_external;
1039
1040/**
1041 * EXPERIMENTAL API - Subject to change
1042 *
1043 * Converts an external verifier to an internal verifier.
1044 * Note that we will not take the ownership of the external_verifier. Callers
1045 * will need to delete external_verifier in its own destruct function.
1046 */
1047grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_external_create(
1048 grpc_tls_certificate_verifier_external* external_verifier);
1049
1050/**
1051 * EXPERIMENTAL API - Subject to change
1052 *
1053 * Factory function for an internal verifier that won't perform any
1054 * post-handshake verification. Note: using this solely without any other
1055 * authentication mechanisms on the peer identity will leave your applications
1056 * to the MITM(Man-In-The-Middle) attacks. Users should avoid doing so in
1057 * production environments.
1058 */
1059grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_no_op_create();
1060
1061/**
1062 * EXPERIMENTAL API - Subject to change
1063 *
1064 * Factory function for an internal verifier that will do the default hostname
1065 * check.
1066 */
1067grpc_tls_certificate_verifier* grpc_tls_certificate_verifier_host_name_create();
1068
1069/**
1070 * EXPERIMENTAL API - Subject to change
1071 *
1072 * Releases a grpc_tls_certificate_verifier object. The creator of the
1073 * grpc_tls_certificate_verifier object is responsible for its release.
1074 */
1075void grpc_tls_certificate_verifier_release(
1076 grpc_tls_certificate_verifier* verifier);
1077
1078/**
1079 * EXPERIMENTAL API - Subject to change
1080 *
1081 * Sets the verifier in options. The |options| will implicitly take a new ref to
1082 * the |verifier|. If not set on the client side, we will verify server's
1083 * certificates, and check the default hostname. If not set on the server side,
1084 * we will verify client's certificates.
1085 */
1086void grpc_tls_credentials_options_set_certificate_verifier(
1087 grpc_tls_credentials_options* options,
1088 grpc_tls_certificate_verifier* verifier);
1089
1090/**
1091 * EXPERIMENTAL API - Subject to change
1092 *
1093 * Sets the options of whether to check the hostname of the peer on a per-call
1094 * basis. This is usually used in a combination with virtual hosting at the
1095 * client side, where each individual call on a channel can have a different
1096 * host associated with it.
1097 * This check is intended to verify that the host specified for the individual
1098 * call is covered by the cert that the peer presented.
1099 * The default is a non-zero value, which indicates performing such checks.
1100 */
1101GRPCAPI void grpc_tls_credentials_options_set_check_call_host(
1102 grpc_tls_credentials_options* options, int check_call_host);
1103
1104/**
1105 * EXPERIMENTAL API - Subject to change
1106 *
1107 * Performs the verification logic of an internal verifier.
1108 * This is typically used when composing the internal verifiers as part of the
1109 * custom verification.
1110 * If |grpc_tls_certificate_verifier_verify| returns true, inspect the
1111 * verification result through request->status and request->error_details.
1112 * Otherwise, inspect through the parameter of |callback|.
1113 */
1114int grpc_tls_certificate_verifier_verify(
1115 grpc_tls_certificate_verifier* verifier,
1116 grpc_tls_custom_verification_check_request* request,
1117 grpc_tls_on_custom_verification_check_done_cb callback, void* callback_arg,
1118 grpc_status_code* sync_status, char** sync_error_details);
1119
1120/**
1121 * EXPERIMENTAL API - Subject to change
1122 *
1123 * Performs the cancellation logic of an internal verifier.
1124 * This is typically used when composing the internal verifiers as part of the
1125 * custom verification.
1126 */
1127void grpc_tls_certificate_verifier_cancel(
1128 grpc_tls_certificate_verifier* verifier,
1129 grpc_tls_custom_verification_check_request* request);
1130
1131/**
1132 * EXPERIMENTAL API - Subject to change
1133 *
1134 * Creates a TLS channel credential object based on the
1135 * grpc_tls_credentials_options specified by callers. The
1136 * grpc_channel_credentials will take the ownership of the |options|. The
1137 * security level of the resulting connection is GRPC_PRIVACY_AND_INTEGRITY.
1138 */
1139grpc_channel_credentials* grpc_tls_credentials_create(
1140 grpc_tls_credentials_options* options);
1141
1142/**
1143 * EXPERIMENTAL API - Subject to change
1144 *
1145 * Creates a TLS server credential object based on the
1146 * grpc_tls_credentials_options specified by callers. The
1147 * grpc_server_credentials will take the ownership of the |options|.
1148 */
1149grpc_server_credentials* grpc_tls_server_credentials_create(
1150 grpc_tls_credentials_options* options);
1151
1152/**
1153 * EXPERIMENTAL API - Subject to change
1154 *
1155 * This method creates an insecure channel credentials object.
1156 */
1157GRPCAPI grpc_channel_credentials* grpc_insecure_credentials_create();
1158
1159/**
1160 * EXPERIMENTAL API - Subject to change
1161 *
1162 * This method creates an insecure server credentials object.
1163 */
1164GRPCAPI grpc_server_credentials* grpc_insecure_server_credentials_create();
1165
1166/**
1167 * EXPERIMENTAL API - Subject to change
1168 *
1169 * This method creates an xDS channel credentials object.
1170 *
1171 * Creating a channel with credentials of this type indicates that the channel
1172 * should get credentials configuration from the xDS control plane.
1173 *
1174 * \a fallback_credentials are used if the channel target does not have the
1175 * 'xds:///' scheme or if the xDS control plane does not provide information on
1176 * how to fetch credentials dynamically. Does NOT take ownership of the \a
1177 * fallback_credentials. (Internally takes a ref to the object.)
1178 */
1179GRPCAPI grpc_channel_credentials* grpc_xds_credentials_create(
1180 grpc_channel_credentials* fallback_credentials);
1181
1182/**
1183 * EXPERIMENTAL API - Subject to change
1184 *
1185 * This method creates an xDS server credentials object.
1186 *
1187 * \a fallback_credentials are used if the xDS control plane does not provide
1188 * information on how to fetch credentials dynamically.
1189 *
1190 * Does NOT take ownership of the \a fallback_credentials. (Internally takes
1191 * a ref to the object.)
1192 */
1193GRPCAPI grpc_server_credentials* grpc_xds_server_credentials_create(
1194 grpc_server_credentials* fallback_credentials);
1195
1196/**
1197 * EXPERIMENTAL - Subject to change.
1198 * An opaque type that is responsible for providing authorization policies to
1199 * gRPC.
1200 */
1201typedef struct grpc_authorization_policy_provider
1202 grpc_authorization_policy_provider;
1203
1204/**
1205 * EXPERIMENTAL - Subject to change.
1206 * Creates a grpc_authorization_policy_provider using gRPC authorization policy
1207 * from static string.
1208 * - authz_policy is the input gRPC authorization policy.
1209 * - code is the error status code on failure. On success, it equals
1210 * GRPC_STATUS_OK.
1211 * - error_details contains details about the error if any. If the
1212 * initialization is successful, it will be null. Caller must use gpr_free to
1213 * destroy this string.
1214 */
1215GRPCAPI grpc_authorization_policy_provider*
1216grpc_authorization_policy_provider_static_data_create(
1217 const char* authz_policy, grpc_status_code* code,
1218 const char** error_details);
1219
1220/**
1221 * EXPERIMENTAL - Subject to change.
1222 * Creates a grpc_authorization_policy_provider by watching for gRPC
1223 * authorization policy changes in filesystem.
1224 * - authz_policy is the file path of gRPC authorization policy.
1225 * - refresh_interval_sec is the amount of time the internal thread would wait
1226 * before checking for file updates.
1227 * - code is the error status code on failure. On success, it equals
1228 * GRPC_STATUS_OK.
1229 * - error_details contains details about the error if any. If the
1230 * initialization is successful, it will be null. Caller must use gpr_free to
1231 * destroy this string.
1232 */
1233GRPCAPI grpc_authorization_policy_provider*
1234grpc_authorization_policy_provider_file_watcher_create(
1235 const char* authz_policy_path, unsigned int refresh_interval_sec,
1236 grpc_status_code* code, const char** error_details);
1237
1238/**
1239 * EXPERIMENTAL - Subject to change.
1240 * Releases grpc_authorization_policy_provider object. The creator of
1241 * grpc_authorization_policy_provider is responsible for its release.
1242 */
1243GRPCAPI void grpc_authorization_policy_provider_release(
1244 grpc_authorization_policy_provider* provider);
1245
1246/** --- TLS session key logging. ---
1247 * Experimental API to control tls session key logging. Tls session key logging
1248 * is expected to be used only for debugging purposes and never in production.
1249 * Tls session key logging is only enabled when:
1250 * At least one grpc_tls_credentials_options object is assigned a tls session
1251 * key logging file path using the API specified below.
1252 */
1253
1254/**
1255 * EXPERIMENTAL API - Subject to change.
1256 * Configures a grpc_tls_credentials_options object with tls session key
1257 * logging capability. TLS channels using these credentials have tls session
1258 * key logging enabled.
1259 * - options is the grpc_tls_credentials_options object
1260 * - path is a string pointing to the location where TLS session keys would be
1261 * stored.
1262 */
1263GRPCAPI void grpc_tls_credentials_options_set_tls_session_key_log_file_path(
1264 grpc_tls_credentials_options* options, const char* path);
1265
1266#ifdef __cplusplus
1267}
1268#endif
1269
1270#endif /* GRPC_GRPC_SECURITY_H */
1271

source code of include/grpc/grpc_security.h